Errors and limits

The error uses the format of the API you called: an object named error for OpenAI, {"type": "error", "error": {...}} for Anthropic, and an error object with status and details fields for Gemini. SDKs therefore recognize them as standard API errors.

• error.code and error.reason — the error class from the table below; the values match. error.type — the format’s standard value (for example, invalid_request_error or server_error).
• error.request_id (at the top level in Anthropic as request_id ), the X-Request-ID header, and the end of the message contain the request ID.
• In Gemini, the class is in error.details: ErrorInfo.reason — the same code in uppercase (for example, MODEL_OVERLOADED), domain — ailoot.ai; the request ID is in RequestInfo.requestId.
• In Gemini format, a 5xx error that must not be retried automatically and result_pending_check are returned with status 409 and status ABORTED: this prevents the Gemini SDK and CLI from retrying them automatically. The error class is in ErrorInfo.reason (for example, MODEL_TIMEOUT or RESULT_PENDING_CHECK).
• OpenAI-format responses also have the top-level fields code and message for older clients.

{
  "code": "API_KEY_REQUIRED",
  "error": {
    "code": "invalid_api_key",
    "message": "No API key was sent with the request. Nothing was charged. Please check that the full key is sent in the Authorization header as \"Bearer <key>\". Request ID: 3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6.",
    "param": null,
    "reason": "invalid_api_key",
    "request_id": "3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6",
    "type": "invalid_request_error"
  },
  "message": "No API key was sent with the request. Nothing was charged. …"
}

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "reason": "invalid_api_key",
    "message": "… Nothing was charged. … Request ID: 94ed3e31-4373-41ce-bf8a-0d1ed3f7235e."
  },
  "request_id": "94ed3e31-4373-41ce-bf8a-0d1ed3f7235e"
}

{
  "error": {
    "code": 401,
    "status": "UNAUTHENTICATED",
    "message": "The API key is not valid. Nothing was charged. … Request ID: e7aa743b-9d0d-4064-b206-2562609f545b.",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_API_KEY",
        "domain": "ailoot.ai",
        "metadata": {
          "code": "invalid_api_key",
          "reason": "invalid_api_key",
          "request_id": "e7aa743b-9d0d-4064-b206-2562609f545b"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.RequestInfo",
        "requestId": "e7aa743b-9d0d-4064-b206-2562609f545b"
      }
    ]
  }
}

Codes for model responses and result verification (502, 503, and 504) now refer to the model or request: model_unavailable, model_timeout, invalid_model_response, incomplete_response, charge_not_confirmed and result_pending_check. If your code compares error.code against the previous values, replace them with the codes in the table. For help mapping old codes to new ones, contact support.

• Check X-Should-Retry first: if you see false, result_pending_check or model_timeout — do not retry automatically. The first item is a header value; the others are error codes. Find the Request ID in your Dashboard history to see the result and charge.
• Retrying is safe when X-Should-Retry: true is returned: wait Retry-After seconds. For 5xx errors, the code alone is not enough: a result may already exist. Check your Dashboard history first or contact support with the Request ID. This is especially important for images, video, music, and long agent steps.
• Retries will not help: for 400, 401, 402, 403, or 404, correct the request, key, or balance first.

Rate and concurrency limits apply to your account as a whole, not to individual keys. Exceeding them returns 429 rate_limit_exceeded with the header Retry-After: 10. If the model itself is overloaded, you receive 503 model_overloaded with Retry-After: 30. If you need a higher load, contact support.

Spending limits are set per key: the total limit returns 402 api_key_quota_exhausted; the 5-hour, 1-day, and 7-day windows return 429 usage_limit_reached. Learn more: API keys and base URL.

You can request the model list with a zero balance, but generation requires enough balance for the reserve. NVIDIA models, including Nemotron, use a shared queue. Under high load, responses may arrive later, or you may receive a “model temporarily overloaded” error with Retry-After; retry after the specified interval. Prices are in the catalog, and charges work the same way as for other models.

Size limits are set by the model: its context window (the number of tokens you can send) and maximum response length. They are listed in the catalog.