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

# Errors

> Parse Yelu AI API errors, understand HTTP status codes, and implement safe retries and observability.

Yelu uses standard HTTP status codes and an OpenAI-compatible JSON error envelope for API failures.

## Error shape

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "message": "The requested model is not available for this key.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}
```

<ResponseField name="error" type="object" required>
  The top-level error object.

  <Expandable title="properties">
    <ResponseField name="message" type="string" required>
      Human-readable diagnostic text. Do not branch application logic on this value.
    </ResponseField>

    <ResponseField name="type" type="string">
      Broad error category, such as `invalid_request_error` or `rate_limit_error`.
    </ResponseField>

    <ResponseField name="param" type="string | null">
      Request field associated with the error, when available.
    </ResponseField>

    <ResponseField name="code" type="string | null">
      Stable machine-oriented code when available.
    </ResponseField>
  </Expandable>
</ResponseField>

## HTTP status codes

| Status              | Meaning                                                                           | Recommended action                                           |
| ------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `400`               | Invalid JSON, unsupported field, invalid value, or incompatible model capability. | Fix the request; do not retry unchanged.                     |
| `401`               | Missing or invalid API key.                                                       | Check Bearer authentication or rotate the key.               |
| `403`               | The key or account is not allowed to perform the operation.                       | Check restrictions, account state, and model access.         |
| `404`               | Endpoint or model not found.                                                      | Verify the path and refresh the model list.                  |
| `408`               | Request timed out before completion.                                              | Retry cautiously with backoff.                               |
| `413`               | Request body or uploaded file is too large.                                       | Reduce content or file size.                                 |
| `422`               | The request is syntactically valid but cannot be processed.                       | Correct the indicated field or capability mismatch.          |
| `429`               | Request limit reached.                                                            | Back off with jitter and reduce concurrency.                 |
| `500`               | Internal gateway error.                                                           | Retry with a small budget and log diagnostics.               |
| `502`, `503`, `504` | Gateway or upstream service is temporarily unavailable.                           | Retry with backoff; use an approved fallback if appropriate. |

## Robust error handling

<CodeGroup>
  ```bash Curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
  status=$(curl -sS -o response.json -w "%{http_code}" \
    https://api.yelu.ai/v1/models \
    -H "Authorization: Bearer $YELU_API_KEY")

  if [ "$status" -ge 400 ]; then
    jq '{status: '"$status"', error: .error}' response.json >&2
    exit 1
  fi
  jq . response.json
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  async function yelu(path, options = {}) {
    const response = await fetch(`https://api.yelu.ai/v1${path}`, {
      ...options,
      headers: {
        Authorization: `Bearer ${process.env.YELU_API_KEY}`,
        'Content-Type': 'application/json',
        ...options.headers,
      },
    });
    const body = await response.json().catch(() => null);
    if (!response.ok) {
      const error = new Error(body?.error?.message ?? `HTTP ${response.status}`);
      error.status = response.status;
      error.code = body?.error?.code;
      throw error;
    }
    return body;
  }
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os
  import requests

  class YeluError(RuntimeError):
      def __init__(self, status, message, code=None):
          super().__init__(message)
          self.status = status
          self.code = code

  def yelu(method, path, **kwargs):
      response = requests.request(
          method,
          f"https://api.yelu.ai/v1{path}",
          headers={"Authorization": f"Bearer {os.environ['YELU_API_KEY']}"},
          timeout=60,
          **kwargs,
      )
      if not response.ok:
          body = response.json() if response.content else {}
          detail = body.get("error", {})
          raise YeluError(response.status_code, detail.get("message", response.text), detail.get("code"))
      return response.json()
  ```
</CodeGroup>

## Operational guidance

* Log HTTP status, error `type`, error `code`, endpoint, model, attempt number, and latency.
* Redact `Authorization`, prompts, tool arguments, image URLs, audio content, and user data according to your privacy policy.
* Set connect and total timeouts; a network request without a timeout can consume workers indefinitely.
* Retry only temporary failures and cap the total time spent retrying.
* Treat streamed responses as partial until the terminal event or `[DONE]` marker arrives.