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

# Errors

> Every error is a JSON object with a stable type and code. 402s carry your top-up URL.

All errors return a JSON body in an OpenAI-compatible shape:

```json theme={null}
{
  "error": {
    "type": "insufficient_credits",
    "code": "insufficient_credits",
    "message": "This app's wallet balance cannot cover the request. Show top_up_url to your user.",
    "doc_url": "https://docs.tokengift.ai/reference/errors#insufficient-credits",
    "balance": "3.21",
    "top_up_url": "https://tokengift.ai/fuel/your-app"
  }
}
```

* `type` — broad category, matching OpenAI's taxonomy where one exists.
* `code` — stable machine-readable identifier for the exact failure. Branch on this.
* `param` — present when the error is about a specific request field.
* `doc_url` — deep link to the matching section on this page.

## Error codes

| HTTP | `type`                  | `code`                 | What to do                                                                                  |
| ---- | ----------------------- | ---------------------- | ------------------------------------------------------------------------------------------- |
| 401  | `authentication_error`  | `invalid_api_key`      | Check the `Authorization: Bearer` header and your key in the dashboard                      |
| 400  | `invalid_request_error` | `invalid_json`         | Request body is not valid JSON                                                              |
| 400  | `invalid_request_error` | `missing_model`        | Add the `model` field (`param: "model"`)                                                    |
| 400  | `invalid_request_error` | `model_not_found`      | See [Models & pricing](/reference/models-pricing) for supported models                      |
| 402  | `insufficient_credits`  | `insufficient_credits` | Show `top_up_url` to your users — see [Handle an empty wallet](/guides/handle-empty-wallet) |
| 404  | `invalid_request_error` | `not_found`            | Check the URL path                                                                          |
| 429  | `rate_limit_error`      | `rate_limit_exceeded`  | Back off for `Retry-After` seconds                                                          |
| 502  | `upstream_error`        | `upstream_unreachable` | Retry with backoff; nothing was charged                                                     |
| 500  | `api_error`             | `internal_error`       | Contact support with your `TokenGift-Request-Id`                                            |

<Note>
  When a request fails after reservation, the full reservation is released — you are never
  charged for failed requests.
</Note>

## Rate limits

Every response includes OpenAI-compatible rate limit headers:

| Header                           | Meaning                                   |
| -------------------------------- | ----------------------------------------- |
| `x-ratelimit-limit-requests`     | Requests allowed per minute for your key  |
| `x-ratelimit-remaining-requests` | Remaining requests in the current window  |
| `x-ratelimit-reset-requests`     | Time until the window resets (e.g. `42s`) |

When you exceed the limit, the response is `429` with a `Retry-After` header in seconds.

## Debugging

Every response carries a `TokenGift-Request-Id` header. Include it when contacting
[support@tokengift.ai](mailto:support@tokengift.ai) and we can trace the exact request.