Errors
Every error has the same shape and a stable code. Branch on the code, show the message.
Error shape
{
"error": {
"code": "insufficient_balance",
"message": "Your balance is too low for this order.",
"hint": "Top up in the dashboard.",
"retryable": false,
"price": "2.50",
"available": "1.20",
"top_up_url": "https://tikiapi.com/dashboard/billing",
"request_id": "…",
"docs_url": "https://tikiapi.com/docs/errors/insufficient_balance"
}
}retryable: truemeans the same request may work if you send it again later.path(oninvalid_parameter) names the field, for exampleduration.request_idhelps us find your request if you contact support.
Request errors
| HTTP | Code | What to do |
|---|---|---|
| 400 | invalid_json | The body isn't valid JSON. Check quotes and commas. |
| 400 | invalid_request | The request doesn't match what the endpoint takes. |
| 400 | invalid_parameter | A field is missing or wrong. path names the field, hint says what is expected. |
| 400 | variant_not_available | The model isn't sold with these settings, for example this resolution. See its prices in GET /v1/models. |
| 401 | invalid_api_key | The key is missing, wrong or revoked. Send Authorization: Bearer tk_… |
| 401 | expired_api_key | The key has expired. Create a new one in the dashboard. |
| 401 | invalid_token | MCP only: the app's sign-in token is expired, revoked or meant for another server. Connect the app again. |
| 402 | insufficient_balance | The balance doesn't cover this order. The error includes price, available and top_up_url. |
| 403 | missing_scope | The key isn't allowed to do this. Create a key with the right permissions. |
| 403 | ip_not_allowed | The key can't be used from this IP address. |
| 403 | origin_not_allowed | The request came from a web page. Call the API from your server. |
| 403 | account_suspended | The account can't use the API right now. Contact support. |
| 404 | not_found | There's no such object, or it belongs to another account. |
| 404 | model_not_found | There's no model with this id. See GET /v1/models. |
| 409 | idempotency_key_reused | This Idempotency-Key was used for a different request. Use a new key. |
| 409 | not_cancelable | The order has already finished. |
| 413 | payload_too_large | The request body is too large. |
| 429 | rate_limited | Too many requests. Wait for the seconds in Retry-After and send again. |
| 429 | key_limit_reached | The key has reached its spending limit. The error includes remaining. |
| 500 | internal | Something went wrong on our side. Send again; if it repeats, contact support with the request_id. |
| 503 | model_unavailable | The model isn't available right now: it is switched off, or no provider can take these settings (then hint and path name the one to change). See GET /v1/models. |
Generation errors
When an order fails, its status is failed and error.code says why. Nothing is charged for a failed order.
| Code | Meaning |
|---|---|
content_refused | The request isn't allowed by the model's or our content rules. |
input_refused | The model refused one of the reference images. |
bad_input_file | A reference image couldn't be read. Check that the link is public and is an image. |
prompt_too_long | The prompt is too long for this model. |
timed_out | The model didn't finish in time. If the result arrives later, you get it free. |
provider_unavailable | The model is unavailable right now. Try again in a few minutes. A hint, when there is one, names a setting that lets more providers take the order. |
canceled | You canceled the order. |
sandbox_failure | A test key order with the word fail in the prompt. Use it to test your error handling. |
