# Error Handling (/docs/errors)


Error Response Format [#error-response-format]

All errors follow a consistent JSON structure:

```json
{
  "error": {
    "type": "invalid_request_error",
    "message": "A human-readable description of the error.",
    "code": "invalid_model",
    "param": "model"
  }
}
```

| Field     | Description                                         |
| --------- | --------------------------------------------------- |
| `type`    | Error category                                      |
| `message` | Human-readable error description                    |
| `code`    | Machine-readable error code                         |
| `param`   | The parameter that caused the error (if applicable) |

HTTP Status Codes [#http-status-codes]

| Status | Type                    | Description                                              |
| ------ | ----------------------- | -------------------------------------------------------- |
| 400    | `invalid_request_error` | The request body is malformed or missing required fields |
| 401    | `authentication_error`  | Invalid or missing API key                               |
| 403    | `permission_error`      | The API key does not have permission for this action     |
| 404    | `not_found_error`       | The requested resource does not exist                    |
| 409    | `conflict_error`        | The request conflicts with current state                 |
| 422    | `validation_error`      | Request parameters failed validation                     |
| 429    | `rate_limit_error`      | Too many requests — rate limit exceeded                  |
| 500    | `internal_error`        | An unexpected error on our servers                       |
| 502    | `upstream_error`        | The upstream provider returned an error                  |
| 503    | `service_unavailable`   | The service is temporarily unavailable                   |

Common Error Codes [#common-error-codes]

Authentication Errors [#authentication-errors]

| Code              | Message                      | Solution                                       |
| ----------------- | ---------------------------- | ---------------------------------------------- |
| `invalid_api_key` | Invalid API key              | Check that your key is correct and not expired |
| `missing_api_key` | Authorization header missing | Include `Authorization: Bearer YOUR_API_KEY`   |
| `key_revoked`     | API key has been revoked     | Generate a new API key from the Dashboard      |

Request Errors [#request-errors]

| Code                      | Message                                 | Solution                                               |
| ------------------------- | --------------------------------------- | ------------------------------------------------------ |
| `invalid_model`           | Model not found                         | Check the model ID against `/v1/models`                |
| `context_length_exceeded` | Input exceeds model context             | Reduce input length or use a model with larger context |
| `invalid_messages`        | Messages format invalid                 | Ensure messages array follows the correct schema       |
| `content_filter`          | Content was filtered                    | Modify your prompt to comply with usage policies       |
| `model_tier_restricted`   | Model requires higher subscription tier | Upgrade your subscription to access this model         |

Provider Errors [#provider-errors]

| Code                   | Message                          | Solution                                                  |
| ---------------------- | -------------------------------- | --------------------------------------------------------- |
| `provider_unavailable` | Provider is currently down       | Try a different model or wait and retry                   |
| `provider_timeout`     | Provider did not respond in time | Retry with a shorter prompt or different model            |
| `upstream_error`       | Provider returned an error       | Check the nested error details for provider-specific info |

Error Handling Example [#error-handling-example]

```python
from openai import OpenAI, APIError, RateLimitError

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.yuhuanstudio.com/v1"
)

try:
    response = client.chat.completions.create(
        model="model-id",
        messages=[{"role": "user", "content": "Hello"}]
    )
except RateLimitError:
    # Wait and retry
    pass
except APIError as e:
    print(f"API error: {e.status_code} - {e.message}")
```