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

# Error codes and handling

> Understand common model API errors, recommended actions, and retry behavior.

ApiGo model APIs use HTTP status codes to communicate request outcomes. The exact fields in an error response follow the compatibility protocol of the endpoint you call, while the status meanings and recommended actions remain consistent.

Do not match complete error messages in application logic. Use the HTTP status first, followed by a structured error type or code when the response provides one.

## HTTP status codes

| Status | Meaning                                                                                   | Recommended action                                                                                 |
| ------ | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `400`  | The request is malformed, invalid, or unsupported by the selected model.                  | Correct the request before retrying.                                                               |
| `401`  | The API key is missing, invalid, or disabled.                                             | Check the authentication method and API key.                                                       |
| `402`  | The account balance is insufficient. Some compatibility protocols use this status.        | Top up the account before retrying.                                                                |
| `403`  | The API key is valid but is not permitted to make this request.                           | Check model permissions, IP allowlists, and key configuration.                                     |
| `404`  | The requested model, task, or resource does not exist or is not accessible with this key. | Check the model name, resource ID, and API key used to create the resource.                        |
| `429`  | A request-rate limit, insufficient balance, or API-key usage limit prevents the request.  | Depending on the error, retry with backoff, top up, change the limit, or wait for the next period. |
| `503`  | ApiGo or an upstream service is temporarily unable to process the request.                | Retry with exponential backoff and jitter.                                                         |

## Understand `402` and `429`

`402` and `429` can both indicate a usage or capacity constraint, but they require different actions:

* **Request-rate or concurrency limit**: reduce the request rate and retry with exponential backoff.
* **Insufficient account balance**: top up before retrying. Repeated automatic retries will not help.
* **API-key usage limit**: raise the configured limit or wait for the current limit period to end.

Structured error fields differ between endpoints. Use the HTTP status together with the available error type or code and the error message to determine the specific cause.

See [Rate limits](/en/api-reference/guide/rate-limits) for additional guidance.

## Response format

Error responses follow the compatibility protocol of the endpoint you call, not the protocol of the selected model or upstream service. As ApiGo adds models and upstream providers, you do not need to add provider-specific error branches.

Compatibility protocols may use different fields such as `type`, `code`, or `status`. These fields do not form one universal enum across all endpoints.

| Information                       | Stability and usage                                                                                                                 |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| HTTP status                       | Use this as the first level of error handling.                                                                                      |
| Structured error type or code     | Follow the API definition or SDK type for the current endpoint. Do not assume field names or values are identical across endpoints. |
| Error message                     | Use it for display and troubleshooting, not exact-string matching in application logic.                                             |
| Additional diagnostic information | It may be omitted or redacted and should not be a business-logic dependency.                                                        |

Use the API definition or SDK types for the endpoint when handling its exact response structure.

## Streaming requests

Streaming requests can fail in two ways:

* If an error occurs before streaming begins, the API returns a normal HTTP error status and error body.
* If an error occurs after streaming begins, the HTTP status may already be `200`, and the error is delivered as an event inside the stream.

Continue reading the stream until it ends normally, and treat an in-stream error event as a failed request. Do not use the initial HTTP `200` alone as proof that a streaming request succeeded.

## Retry and troubleshooting

* Do not automatically retry `400`, `401`, `402`, `403`, or `404` unless you have corrected the underlying problem.
* Automatically retry `429` only when it represents a request-rate limit. Balance and key-limit errors require an account or configuration change.
* Retry `503` a limited number of times with exponential backoff and random jitter.
* Record the request time, endpoint, HTTP status, and structured error type. Record [`x-apigo-request-id`](/en/api-reference/guide/request-ids) as well when the response provides one.
* Never include complete API keys in logs or support requests.

To protect platform and upstream details, ApiGo normalizes some failures into a generic `503`. These responses do not expose the internal or upstream cause.