# Error Codes


A quick reference for errors and rate limits when calling **Genesis / model APIs**. For service-specific error codes, response-body field names, and rate-limit values, follow the live API and key configuration. Handle codes not listed in the table according to the API response.

For authentication, endpoints, and examples, see [Developer](../../developer/index.md) and [Genesis](../../guides/genesis/index.md).

## Authentication

The model API uses **OpenAI-compatible** authentication and accepts only:

```http
Authorization: Bearer <API_KEY>
```

As with the OpenAI SDK, set `api_key` to the Genesis Key and point `base_url` to Genesis. Create an API Key under “Keys” in Genesis. The UI might mask the key; when copying it, use the actual value. Do not commit it to a code repository.

## HTTP Statuses and Handling

Based on HTTP and OpenAI-compatible conventions:

| Status code | Meaning | Recommended action |
| --- | --- | --- |
| 400 | Invalid request parameters | Check fields and values; **do not** retry blindly |
| 401 | Authentication failed | Check whether the Key is correct, disabled, or expired; verify the header name |
| 403 | Permission denied / model not enabled for the key | Enable the model for the key or use a different key |
| 404 | Endpoint or model does not exist | Verify the Base URL and `model` |
| 429 | Rate limit reached or quota exhausted | Retry with backoff; or request a higher quota / reduce concurrency / wait for the daily quota to reset |
| 5xx | Server error | Retry after backoff; idempotent requests can be retried safely |

Error response skeleton (the actual API determines the structure):

```json
{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Rate limit reached for this API key.",
    "code": "429"
  }
}
```

## Rate Limits and Quotas

Calls are subject to **two layers** of constraints. Reaching either limit rejects the request:

| Layer | Description |
| --- | --- |
| Key-level rate | Concurrency, RPM (requests per minute), and similar limits |
| Key-level quota | Total quota, daily quota, and similar limits |

A rate limit commonly produces **HTTP 429**. If the response includes `Retry-After`, wait for the specified number of seconds first.

**Retry recommendation**: Use exponential backoff + jitter for **429 and 5xx**. Do not retry other 4xx responses.

## Symptom Reference

| Symptom | Possible cause | Action |
| --- | --- | --- |
| Returns 429 | Rate limit reached or quota exhausted | Reduce concurrency and back off; increase the quota or wait for the daily quota to reset |
| Quota is repeatedly exhausted | Quota is too low or multiple business lines share one Key | Use separate Keys by business line and monitor the usage dashboard |
| 403 for a specific model | Model is not in the key's available model scope | Change the model or the key configuration |
| Model suddenly becomes unavailable | Marketplace status issue / model removed | Check the model status in Genesis and switch to an available model of the same type; you can also enable availability notifications |
| Authentication failed | Key is wrong / expired, or `Authorization: Bearer` was not used | Verify the OpenAI-style request header and Key; recreate the Key if necessary |
| OpenAI SDK error | Base URL does not point to Genesis, or `api_key` is not a Genesis Key | Correct `base_url` and `api_key` |
| Billing differs from expectations | Cache billing or API-type billing rules differ | Compare the integration instructions with the usage details |
| Request rejected for insufficient balance | Insufficient Credit | Add funds under [Costs and Billing](../../guides/billing/index.md), then retry |
| Undocumented error code | — | Follow the API response; if necessary, provide the request and response when contacting support |

Parameters and billing rules differ among API types (Chat / Embeddings / OCR / Image / Video / TTS / ASR, and others). Before calling an API, consult the integration instructions for that type.