Error Handling - Unifically

Every error the API returns carries three things:

an HTTP status that tells you the class of failure,
a stable error code (error_code on task endpoints, code on LLM endpoints) that tells you the exact reason, so your code can branch on it without parsing the message,
a request_id you can quote to support so we can find the exact request in our logs.

Unifically uses two error shapes:

Task endpoints (/v1/tasks, /v1/account, /v1/resources) wrap every response in a { success, code, data } envelope. See Task Endpoints.
LLM endpoints (/v1/chat/completions, /v1/responses, /v1/messages, /v1/models) return the provider-native error shape. See LLM Endpoints.

The error codes themselves are the same on both. See Error Codes for the full list.

Task Endpoints

Response Structure

Success Response

{
  "success": true,
  "code": 200,
  "data": {
    // Response data
  }
}

Error Response

{
  "success": false,
  "code": 401,
  "data": {
    "message": "API key is required",
    "error_code": "api_key_missing",
    "request_id": "52e2bafd-654e-4099-a562-c8c10a2b9e5f"
  }
}

Empty arrays and objects are omitted from responses when not needed.

Response Fields

boolean

Indicates whether the request was successful (true) or failed (false)

integer

HTTP status code of the response

object

Response data on success, error details on failure

string

Human-readable description of the error. Safe to show to your users

string

Stable machine-readable reason. Present when the failure has a defined code (see Error Codes). Branch on this, not on message, since message text can change

string

Unique id of this request. Include it when contacting support. On 5xx responses the same id is also appended to message

HTTP Status Codes

Code	Meaning	Description
`200`	Success	Task successfully submitted
`400`	Bad Request	The provider rejected the request, the JSON body is malformed (code `invalid_json`), or a media URL is not allowed
`401`	Unauthorized	Missing, invalid, or expired API key
`402`	Payment Required	Insufficient balance. Top up in the dashboard
`403`	Forbidden	Key disabled, key not allowed to use this model or from this IP, key spend limit reached, or account banned
`404`	Not Found	Unknown task, model, or resource
`409`	Conflict	An `Idempotency-Key` request is still in progress, or its original response was a stream
`422`	Validation Error	Invalid request parameters (code `invalid_parameter`), or an `Idempotency-Key` reused with a different body
`429`	Too Many Requests	Account rate limit or concurrency limit exceeded
`500`	Internal Server Error	Server error occurred. Retry after a brief delay
`503`	Service Unavailable	No channel can serve the model right now (code `no_channels_available`), or a dependency is unavailable. Retry later
`540`	Model Disabled	The model is switched off on purpose (`error_code: model_disabled`). Do not retry. Check unifically.com/models for a replacement

Example Error Responses

Missing API key (401)

{
  "success": false,
  "code": 401,
  "data": {
    "message": "API key is required",
    "error_code": "api_key_missing",
    "request_id": "52e2bafd-654e-4099-a562-c8c10a2b9e5f"
  }
}

Solution: Send your key in the Authorization header:

Authorization: Bearer YOUR_ACTUAL_API_KEY

Insufficient balance (402)

{
  "success": false,
  "code": 402,
  "data": {
    "message": "need at least $0.120000, available: $0.031500",
    "error_code": "insufficient_balance",
    "request_id": "9f1c2d3e-4b5a-4c6d-8e7f-0a1b2c3d4e5f"
  }
}

Solution: Top up in the dashboard. The request was not billed

Model not allowed for this key (403)

{
  "success": false,
  "code": 403,
  "data": {
    "message": "This API key is not allowed to use model veo-3.1",
    "error_code": "model_not_allowed",
    "request_id": "1b2c3d4e-5f60-4718-8293-a4b5c6d7e8f9"
  }
}

Solution: Edit the key’s allowed models in the dashboard, or use a key without a model restriction

Rate limit exceeded (429)

{
  "success": false,
  "code": 429,
  "data": {
    "message": "Rate limit exceeded. Please try again later",
    "error_code": "rate_limit_exceeded",
    "request_id": "7a8b9c0d-1e2f-4a3b-9c4d-5e6f7a8b9c0d"
  }
}

Solution: Implement exponential backoff and respect rate limits

Validation error (422)

{
  "success": false,
  "code": 422,
  "data": {
    "message": "Missing required parameter: prompt",
    "error_code": "invalid_parameter",
    "request_id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f"
  }
}

Solution: Check the model’s documentation for required parameters and valid values. The message names the parameter

Model disabled (540)

{
  "success": false,
  "code": 540,
  "data": {
    "message": "This model is currently disabled",
    "error_code": "model_disabled",
    "request_id": "3d4e5f6a-7b8c-4d9e-8f0a-1b2c3d4e5f6a"
  }
}

Solution: Do not retry. Pick a replacement at unifically.com/models

Server error (500)

{
  "success": false,
  "code": 500,
  "data": {
    "message": "Internal server error occurred. Please contact support with request id 4e5f6a7b-8c9d-4e0f-9a1b-2c3d4e5f6a7b.",
    "request_id": "4e5f6a7b-8c9d-4e0f-9a1b-2c3d4e5f6a7b"
  }
}

Solution: Retry the request after a brief delay. Contact support with the request id if the issue persists. Failed requests are not billed

LLM Endpoints

The LLM endpoints do not use the { success, code, data } envelope. They return the error shape of the API they are compatible with, so drop-in OpenAI and Anthropic clients parse it natively. The code and request_id fields are the same values as error_code and request_id on task endpoints. /v1/chat/completions, /v1/responses, and /v1/models return OpenAI-style errors:

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "param": null,
    "code": "api_key_invalid",
    "request_id": "52e2bafd-654e-4099-a562-c8c10a2b9e5f"
  }
}

/v1/messages returns Anthropic-style errors:

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key",
    "code": "api_key_invalid",
    "request_id": "52e2bafd-654e-4099-a562-c8c10a2b9e5f"
  }
}

The type field follows the status: authentication_error (401), permission_error (403), not_found_error (404), rate_limit_error (429), invalid_request_error (other 4xx), and service_unavailable (OpenAI-style) or api_error (Anthropic-style) for 5xx. Billing failures on /v1/chat/completions and /v1/responses use type insufficient_balance or billing_error. Use code for the exact reason.

HTTP Status Codes

Code	Meaning	Description
`400`	Bad Request	Invalid request (type `invalid_request_error`), including requests the upstream provider rejects, input larger than the model’s context window (code `context_length_exceeded`), and a model that does not serve `/v1/responses`; use `/v1/chat/completions` for it
`401`	Unauthorized	Missing, invalid, or expired API key (type `authentication_error`)
`402`	Payment Required	Insufficient balance (code `insufficient_balance`). Top up in the dashboard
`403`	Forbidden	Key disabled, key not allowed to use this model or from this IP, key spend limit reached, or account banned
`404`	Not Found	Unknown model (code `model_not_found`)
`409`	Conflict	An `Idempotency-Key` request is still in progress, or its original response was a stream
`422`	Validation Error	An `Idempotency-Key` reused with a different body
`429`	Too Many Requests	Account rate limit or concurrency limit exceeded, or the upstream provider is rate limiting (code `upstream_rate_limited`)
`503`	Service Unavailable	No available channel for the model (code `no_channels_available`) or a provider server error (code `service_unavailable`). Retry later
`540`	Model Disabled	The model is switched off on purpose (code `model_disabled`). Do not retry. Check unifically.com/models for a replacement

On /v1/chat/completions, a 400 is also returned when messages is empty or not an array, or when a message has a role other than system, developer, user, assistant, tool, or function.

Errors During Streaming

Once a stream has started, the HTTP status is already 200. A later error arrives inside the stream, in the same shape as a non-stream error and with the same code and request_id:

/v1/chat/completions: a data: chunk with an error object.

data: {"error": {"message": "...", "type": "...", "code": "...", "param": null, "request_id": "..."}}

/v1/responses: an error event, with no [DONE] after it.

event: error
data: {"type": "error", "code": "...", "message": "...", "param": null, "request_id": "...", "sequence_number": 12}

/v1/messages: an error event.

event: error
data: {"type": "error", "error": {"type": "...", "message": "...", "code": "...", "request_id": "..."}}

On chat completions, check each chunk for error before reading choices. On the other two, handle the error event. Treat it as a failed request. The most common in-stream error is insufficient_balance: your balance ran out mid-generation. You are billed only for the tokens received before the stop.

Error Codes

The code is data.error_code on task endpoints and error.code on LLM endpoints. Codes are stable: a code’s meaning never changes, and new codes may be added. The messages next to them are examples and may be reworded. An error without a code is an internal failure; the HTTP status says all there is to say about it.

Authentication

Code	Status	Why you got it	What to do
`api_key_missing`	401	The request had no `Authorization: Bearer <key>` header, or the header was empty	Send your API key in the header
`api_key_invalid`	401	No key with that value exists. Usually a typo, a key copied with extra characters, or a key from another account	Copy the key again from the dashboard
`api_key_expired`	401	The key has an expiry date set in the dashboard and that date has passed	Extend the date or create a new key
`api_key_disabled`	403	The key was switched off in the dashboard. It still exists but cannot be used	Enable it in the dashboard or use another key
`api_key_revoked`	403	The key was deleted in the dashboard	Create a new key
`ip_not_allowed`	403	The key has an IP allowlist and the request came from an IP that is not on it. The message names the IP	Add that IP to the key, or use a key without an IP restriction
`account_banned`	403	The account is banned, so no key on it works. The message carries the account id and email	Contact support quoting the message

Models and access

Code	Status	Why you got it	What to do
`model_not_found`	404	No model has that id. Usually a typo or an old id	Check the id against `/v1/models` or unifically.com/models
`model_disabled`	540	We switched the model off on purpose, for example because the provider retired it or it is unreliable	Do not retry. Pick a replacement from the models page
`model_not_allowed`	403	The key has an allowed-models list and this model is not on it	Add the model to the key, or use a key without a model restriction
`unsupported_model`	400	The model exists but is not a language model, so it cannot be used on the LLM endpoints	Use the task endpoints for this model
`missing_model`	400	The LLM request had no `model` field	Add the `model` field
`context_length_exceeded`	400	The LLM input is larger than the model’s context window. The message gives the estimate and the limit	Shorten the input or pick a model with a larger context

Request validation

Code	Status	Why you got it	What to do
`invalid_parameter`	422	A parameter is missing, has the wrong type, or has a value outside the allowed range. The message names the parameter and the rule it broke	Fix the parameter as the message describes. Each model page lists its parameters
`invalid_request`	400	On LLM endpoints, the `messages` array is malformed: empty, a message with an unknown role, or wrong content shape. The message says which message and why	Fix the messages array
`invalid_json`	400	The request body is not valid JSON, for example a trailing comma, unquoted key, or a truncated body	Validate the JSON before sending

Billing

Code	Status	Why you got it	What to do
`insufficient_balance`	402	Your available balance is below the maximum this request could cost. We reserve the maximum before running, so a request can be refused even when the final cost would have been lower. Also sent inside a stream when the balance runs out mid-generation	Top up in the dashboard. A refused request is not charged
`api_key_spend_limit_exceeded`	403	The key has a monthly or lifetime spend limit and this request would go over it. The message gives spent, limit, and the reset date for monthly limits	Raise the limit in the dashboard or use another key

Rate limits

Code	Status	Why you got it	What to do
`rate_limit_exceeded`	429	Your account sent more LLM tokens in the last minute than its tokens-per-minute limit allows	Back off and retry. Contact support to raise the limit
`concurrency_limit_exceeded`	429	Your account has more requests running at the same time than its in-flight limit allows	Wait for running requests to finish, then retry

Idempotency

These apply only when you send an Idempotency-Key header. The header makes a repeated request with the same key, body, and route return the original response instead of running again. Keys are scoped to the API key that sent them.

Code	Status	Why you got it	What to do
`idempotency_key_invalid`	400	The key is empty, longer than 255 characters, or contains spaces or non-printable characters	Fix the key format
`idempotency_key_reused`	422	You sent this key before with a different body or to a different route. We refuse rather than guess which request you meant	Use a new key for a new request
`idempotency_key_in_progress`	409	The first request with this key is still running, so there is no response to replay yet. `Retry-After` is set	Retry in a moment to receive its result
`idempotency_key_streamed`	409	The first request with this key was a streamed response. Streams are not stored, so they cannot be replayed. The message names the task id if there is one	Use the task id, or send a new request with a new key

Upstream providers

Code	Status	Why you got it	What to do
`upstream_error`	4xx	The provider behind the model rejected the request, for example an unsupported parameter for that model or content the provider refuses. The message is the provider’s reason where we can pass it on	Fix the request as the message describes
`upstream_rate_limited`	429	The provider behind the model is rate limiting us right now, and no other channel for the model could take the request	Retry with backoff. Failed requests are not billed
`no_channels_available`	503	Every channel we have for this model failed or is unavailable right now. We already tried each one before returning this	Retry with backoff. Failed requests are not billed
`service_unavailable`	503	The provider or one of our dependencies returned a server error. Temporary	Retry with backoff. Failed requests are not billed

Best Practices

Branch on the code

Use error_code / code to decide what to do. Fall back to the HTTP status when there is no code

Implement Retry Logic

Retry with exponential backoff on 429, 500, and 503. Never retry 540 or 402

Log the request id

Log every error response with its request_id. Support can trace a request by that id alone

Check streams too

An error can arrive inside a 200 stream. Handle the error chunk or event like a failed request

Show the error message to your users: data.message on task endpoints, error.message on LLM endpoints

Never expose your API key in client-side code or public repositories

​Task Endpoints

​Response Structure

​Success Response

​Error Response

​Response Fields

​HTTP Status Codes

​Example Error Responses

​LLM Endpoints

​HTTP Status Codes

​Errors During Streaming

​Error Codes

​Authentication

​Models and access

​Request validation

​Billing

​Rate limits

​Idempotency

​Upstream providers

​Best Practices

Branch on the code

Implement Retry Logic

Log the request id

Check streams too

Task Endpoints

Response Structure

Success Response

Error Response

Response Fields

HTTP Status Codes

Example Error Responses

LLM Endpoints

HTTP Status Codes

Errors During Streaming

Error Codes

Authentication

Models and access

Request validation

Billing

Rate limits

Idempotency

Upstream providers

Best Practices