> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeycomb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Handle Honeycomb API errors using standard HTTP status codes and structured error responses.

The Honeycomb API uses standard HTTP status codes and returns structured error responses
that describe what went wrong.
The response format depends on which API version the endpoint uses.

## Error Response Formats

Honeycomb uses two error formats depending on the API version.

<Tabs>
  <Tab title="V1 Endpoints">
    V1 endpoints return errors in RFC7807 Problem Detail format:

    ```json theme={}
    {
    "status": 404,
    "type": "https://api.honeycomb.io/problems/not-found",
    "title": "The requested resource cannot be found.",
    "error": "Dataset not found",
    "detail": "Dataset not found"
    }
    ```

    | Field    | Description                                           |
    | -------- | ----------------------------------------------------- |
    | `status` | HTTP status code.                                     |
    | `type`   | URI that identifies the error type.                   |
    | `title`  | Human-readable summary of the error type.             |
    | `error`  | Description of the error.                             |
    | `detail` | Additional detail about this specific error instance. |

    <Note>
      Some V1 endpoints return a simpler legacy format with only an `error` field:

      ```json theme={}
      { "error": "unknown API key - check your credentials" }
      ```
    </Note>
  </Tab>

  <Tab title="V2 Endpoints">
    V2 endpoints return errors in JSON:API format:

    ```json theme={}
    {
    "errors": [
        {
        "id": "06dcdd6508ca822f0e7e2bb4121c1f52",
        "code": "invalid",
        "title": "request body could not be parsed",
        "detail": "invalid gzip data"
        }
    ]
    }
    ```

    | Field    | Description                                           |
    | -------- | ----------------------------------------------------- |
    | `id`     | A unique identifier for this error instance.          |
    | `code`   | A machine-readable error code.                        |
    | `title`  | A human-readable summary of the error.                |
    | `detail` | Additional detail about this specific error instance. |
  </Tab>
</Tabs>

## HTTP Status Codes

| Status | Name                   | Description                                                                                                                                      |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | Bad Request            | The request body could not be parsed or is invalid. Check the request format and content type.                                                   |
| `401`  | Unauthorized           | The API key is missing or invalid. Check your credentials.                                                                                       |
| `403`  | Forbidden              | The API key does not have permission for this operation. Check the key's permissions or scopes.                                                  |
| `404`  | Not Found              | The requested resource does not exist. Check the resource identifier in your request.                                                            |
| `409`  | Conflict               | The request conflicts with the current state of the resource, such as a duplicate name.                                                          |
| `413`  | Payload Too Large      | The request body exceeds the maximum allowed size of 100,000 bytes.                                                                              |
| `415`  | Unsupported Media Type | The `Content-Type` header does not match what the endpoint expects. Check the [content type](/api/introduction#content-types) for this endpoint. |
| `422`  | Validation Failed      | The request was valid but contained invalid values. The response body includes details about which fields failed validation.                     |
| `429`  | Rate Limited           | You have exceeded the rate limit. For details, visit [Rate Limits](/api/rate-limit).                                                             |
| `500`  | Internal Server Error  | An unexpected error occurred on Honeycomb's side. If this persists, contact [Honeycomb Support](https://support.honeycomb.io/).                  |

## Validation Errors

`422` responses include a `type_detail` array that identifies which fields failed and why:

```json theme={}
{
  "status": 422,
  "type": "https://api.honeycomb.io/problems/validation-failed",
  "title": "The provided input is invalid.",
  "error": "The provided input is invalid.",
  "type_detail": [
    {
      "field": "type",
      "code": "invalid",
      "description": "type: must be a valid value"
    }
  ]
}
```

| Validation code  | Meaning                                        |
| ---------------- | ---------------------------------------------- |
| `invalid`        | The field value is not acceptable.             |
| `missing`        | A required field was not provided.             |
| `incorrect_type` | The field value is the wrong data type.        |
| `already_exists` | The value conflicts with an existing resource. |