Errors

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

{
  "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 for supported models
402	`insufficient_credits`	`insufficient_credits`	Show `top_up_url` to your users — see Handle an 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`

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

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 and we can trace the exact request.

Get Started

Guides

Reference

Error codes

Rate limits

Debugging

​Error codes

​Rate limits

​Debugging

Error codes

Rate limits

Debugging