SkillRouter
Documentation menu

API

Errors

Handle stable SkillRouter codes instead of provider-specific failures.

Error shape

JSON
{
  "error": {
    "code": "insufficient_credits",
    "message": "Available credits do not cover the request reservation."
  },
  "request_id": "sr_req_xxxxxxxxx"
}

Stable codes

  • invalid_api_key — HTTP 401. Retry only with a valid key. It is pre-stream.
  • api_key_rotation_conflict — HTTP 409. Wait for active requests to settle before you rotate again. It is pre-stream.
  • account_disabled — HTTP 403. Retry only after the account is restored. It is pre-stream.
  • insufficient_credits — HTTP 402. Add credits or reduce the request limit. It is pre-stream.
  • invalid_payment — HTTP 400. Correct the payment request. Do not retry it unchanged.
  • invalid_reservation — HTTP 400. Do not retry it unchanged. Record the request ID for support.
  • invalid_model — HTTP 404. Select an active model. It is pre-stream.
  • invalid_skill — HTTP 404. Select an active, published skill version. It is pre-stream.
  • unsupported_capability — HTTP 422. Change the model or requested feature. It is pre-stream.
  • rate_limit_exceeded — HTTP 429. Wait for Retry-After, when present. It is pre-stream.
  • provider_rate_limit — HTTP 429. Use Retry-After and backoff. It can occur during a stream.
  • provider_unavailable — HTTP 502 or 503. Use bounded backoff only when no output was received. It can occur during a stream.
  • provider_timeout — HTTP 504. Use bounded backoff only when no output was received. It can occur during a stream.
  • request_cancelled — HTTP 499 when a response is possible. The connection can close without an error body.
  • request_too_large — HTTP 413. Reduce the request body. It is pre-stream.
  • invalid_request — HTTP 400 or 403. Correct the request. An upstream failure can occur during a stream.
  • billing_unavailable — HTTP 503. Check request history before retrying because metering reconciliation can be pending. It can occur during a stream.
  • catalog_not_ready — HTTP 409. Retry only after an operator corrects the catalog.
  • spend_limit_exceeded — HTTP 402 or 403. Raise the limit, reduce the request, or wait for the limit period to reset.
  • production_resale_disabled — HTTP 503. Select an authorized route or enable it after commercial authorization.
  • internal_error — HTTP 500. Use bounded backoff only when no output was received. It can occur during a stream.
After HTTP 200, a stream error is a final chat.completion.chunk with top-level error, request_id, an empty delta, and finish_reason error, followed by [DONE]. Check error before choices. Do not automatically repeat a request after partial output or billing_unavailable.

Log the SkillRouter request ID. Do not branch on raw upstream provider text because it is intentionally normalized and can change independently.