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

# Errors

> The error object, HTTP statuses and error codes.

Non-2xx responses return an `error` object:

```json theme={"dark"}
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "requests.3.custom_id: 1 to 64 letters, digits, '_' and '-', unique in the batch",
    "retryable": false,
    "request_id": "req_6f1c0d9e2b7a4c3d8e5f1a2b"
  }
}
```

| Field | Description |
| - | - |
| `type` | The error category. See [statuses](#statuses) |
| `code` | A stable code to handle errors by. Codes are not renamed or reused |
| `message` | A human-readable description. Wording may change |
| `retryable` | Whether the identical request may succeed later |
| `request_id` | The request's ID, for support |
| `action_url` | On `out_of_credit` only: the page to [add credit](https://docs.metaphi.ai/account/credit.md) |

Every response includes a `Request-Id` header. Retryable errors may include `Retry-After`, in seconds.

## Statuses

| Status | Type | Meaning |
| - | - | - |
| 400 | `invalid_request_error` | Invalid request; `message` names the parameter |
| 401 | `auth_error` | No API key, a key that does not work, or a sign-in billed to no organization |
| 403 | `auth_error`, `invalid_request_error` | The key does not have access to what it called, or test mode's 5 twins per organization per 24 hours are used |
| 404 | `invalid_request_error` | No such object for this key, or no such route |
| 405 | `invalid_request_error` | The route does not take that method |
| 409 | `idempotency_error`, `invalid_request_error` | An idempotency key conflict, or an object in the wrong status for the request |
| 410 | `invalid_request_error` | The twin's content can no longer be downloaded |
| 413 | `invalid_request_error` | The file, or the request body, is too large |
| 500 | `api_error` | An unexpected failure; nothing was created or charged |
| 503 | `api_error` | Unavailable for a moment; retry after `Retry-After` |

No request fails for lack of credit. A twin or batch the organization can't cover is accepted and pauses until credit is added or other twins finish; see [item errors](#item-errors).

## Codes

The complete set of API error codes. For signing in, keys and organizations, see the [account](https://docs.metaphi.ai/account/keys.md) pages.

| Code | Status | Retryable | Meaning |
| - | - | - | - |
| `missing_api_key` | 401 | no | No API key was sent |
| `invalid_api_key` | 401 | no | The API key is unknown, revoked or mistyped |
| `no_organization` | 401 | no | The sign-in is not billed to an organization; use an organization API key |
| `insufficient_scope` | 403 | no | The API key does not have access to what it called |
| `auth_unavailable` | 503 | yes | The API key could not be checked; nothing was created |
| `balance_unavailable` | 503 | yes | The balance could not be checked; nothing was created |
| `test_quota_exhausted` | 403 | no | Test mode: 5 twins per organization per 24 hours used; use a live key |
| `invalid_filename` | 400 | no | The file name is not one the upload takes |
| `invalid_end_user` | 400 | no | `end_user` is not 1 to 128 letters, digits, `.`, `_`, `:` and `-` |
| `parameter_invalid` | 400 | no | A parameter is missing or invalid; the message names it, such as `requests.3.file_id` |
| `parameter_unknown` | 400 | no | The request has a field the route does not take; the message names it |
| `json_invalid` | 400 | no | The body is not valid JSON |
| `unknown_api_version` | 400 | no | `Metaphi-Version` names no version this API serves |
| `body_invalid` | 400 | no | The request body could not be read |
| `file_empty` | 400 | no | The uploaded file is empty |
| `file_unsupported` | 400 | no | The file is not JSON, JSON Lines or UTF-8 text |
| `file_in_use` | 409 | no | The file is in a batch and cannot be deleted |
| `file_too_large` | 413 | no | The file is over 50 MiB, or 2 MiB in test mode. Split it and upload each part |
| `body_too_large` | 413 | no | The request body is over its route's limit: 4 MiB for a batch, 64 KiB for any other JSON body |
| `idempotency_key_invalid` | 400 | no | The `Idempotency-Key` header is empty, too long or not printable ASCII |
| `idempotency_key_reused` | 409 | no | The `Idempotency-Key` was used with a different request in the last 24 hours |
| `idempotency_key_in_use` | 409 | yes | A request with the same `Idempotency-Key` is still being handled |
| `resource_missing` | 404 | no | No such object for this key's organization and mode |
| `route_missing` | 404 | no | No such route |
| `method_not_allowed` | 405 | no | The route does not take that method |
| `twin_not_completed` | 409 | yes | The twin has not completed; its content is not ready |
| `twin_failed` | 409 | no | The twin failed and has no content |
| `content_expired` | 410 | no | The twin's content can no longer be downloaded |
| `batch_already_ended` | 409 | no | The batch has ended |
| `batch_not_ended` | 409 | yes | The batch has not ended; its results are not ready |
| `webhook_url_invalid` | 400 | no | The webhook URL is not https, or not on a public host |
| `webhook_endpoint_limit` | 400 | no | The organization already has as many webhook endpoints as it may |
| `webhooks_unavailable` | 503 | yes | Webhooks are not available just now |
| `unavailable` | 503 | yes | The request could not be handled; nothing was created or charged |
| `internal_error` | 500 | yes | An unexpected failure; nothing was created or charged |

## Twin failures

A twin with `status: failed` has an `error` object, `{type, code, message, retryable, action_url}`, also set on its [batch item](https://docs.metaphi.ai/kennet/api/batches.md#the-batch-item-object) and in the `kennet.twin.failed` event. Failed twins are not charged. Unsupported formats are refused at upload with `400 file_unsupported`.

| Code | Type | Retryable | Meaning |
| - | - | - | - |
| `not_text` | `run_error` | no | The trace is not JSON, JSON Lines or UTF-8 text |

A twin fails only when its trace causes it. Errors on our side are retried automatically, and an exhausted balance pauses the twin.

## Item errors

A [batch item](https://docs.metaphi.ai/kennet/api/batches.md#the-batch-item-object) has an `error` object, `{type, code, message, retryable, action_url}`, when its status is `failed`, `expired` or `paused`. A `failed` item with a twin carries that twin's [failure](#twin-failures). A request that fails before its twin is created sends `kennet.batch_item.failed`.

| Code | Type | Status | Cause | Resolution |
| - | - | - | - | - |
| `out_of_credit` | `billing_error` | `paused` | The organization ran out of credit | Add credit at `action_url`; the item resumes by itself |
| `batch_expired` | `api_error` | `expired` | The batch expired before the request ended | Send the file in a new batch |
| `test_quota_exhausted` | `invalid_request_error` | `failed` | Test mode: 5 twins per organization per 24 hours used | Use a live key |

Items cancelled before starting have `status: cancelled` and no error.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.