Inference Errors

Inference API Errors

Errors from the Inference API (/v1/chat/completions, /v1/responses, /v1/embeddings) follow an OpenAI-compatible schema with additional Skytells-specific fields for stable programmatic handling.

Error Schema

{
  "error": {
    "message": "Human readable description of the error",
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "error_id": "INVALID_PARAMETER",
    "status": 400,
    "param": "model",
    "request_id": "req_abc123xyz",
    "details": {
      "category": "request"
    }
  }
}

Schema Fields

Notes

• error.type and error.code mirror the OpenAI error format for drop-in compatibility.
• error.error_id is the stable, uppercase identifier intended for programmatic handling.
• Provider/upstream failures are always sanitized — errors never expose infrastructure or upstream details.
• error.details is optional and safe. It will never contain sensitive information.

Using request_id

If you contact support or need to investigate a failed request, include error.request_id. It uniquely identifies the request in Skytells logs and allows the support team to trace the full execution path.

Error Catalog

Authentication & Authorization

UNAUTHORIZED — 401

When: The x-api-key header is missing, expired, or invalid.

Resolution: Verify your API key in the Console and ensure it is sent as x-api-key: YOUR_KEY. See Authentication.

FORBIDDEN — 403

When: The API key is valid but does not have access to the requested resource or model.

Resolution: Ensure your key has the required permissions. Contact Support if access should be granted.

Request Validation

INVALID_REQUEST — 400

When: The request body is malformed JSON or has an invalid shape.

Resolution: Validate your JSON payload and ensure it matches the endpoint schema. Set Content-Type: application/json.

INVALID_PARAMETER — 400

When: A required parameter is missing or a parameter has an invalid value (e.g. missing model, messages not an array).

Resolution: Check error.param for the offending field. Review the request schema.

MODEL_NOT_FOUND — 404

When: The model namespace provided is unknown or not available on the Inference API.

Resolution: Use a valid namespace from the Text Models catalog: deepbrain-router, gpt-5, or gpt-5.4.

ENDPOINT_NOT_FOUND — 404

When: The requested path does not match any supported endpoint.

Resolution: Use a supported endpoint: /v1/chat/completions, /v1/responses, or /v1/embeddings. See the Inference overview.

Billing & Credits

INSUFFICIENT_CREDITS — 402

When: Your account balance is insufficient for the request (including a safety margin).

Resolution: Add credits in the Billing section, or reduce usage by shortening prompts or lowering max_tokens.

CREDIT_CHECK_FAILED — 402

When: The credit-verification service was temporarily unreachable and could not confirm your balance.

Resolution: Retry the request. If the problem persists, contact Support with error.request_id.

Rate Limiting

RATE_LIMITED — 429

When: Too many requests sent in a short time window.

Resolution: Implement exponential backoff — start at 1 s, doubling each retry. The Retry-After response header indicates the wait time. See Rate Limits.

INFERENCE_RATE_LIMITED — 503

When: The inference layer is temporarily busy or rate-limited at the infrastructure level.

Resolution: Retry with exponential backoff. Consider reducing concurrency. This is transient.

Inference (Sanitized)

All inference-level errors are sanitized — no upstream or infrastructure details are ever exposed.

INFERENCE_TIMEOUT — 504

When: The inference request exceeded the maximum allowed time.

Resolution: Retry the request. If it persists, reduce max_tokens or shorten the prompt. Avoid extremely long generations.

SERVICE_UNAVAILABLE — 503

When: The inference service is temporarily unavailable.

Resolution: Retry with exponential backoff. Check status.skytells.ai for active incidents.

INFERENCE_ERROR — 500

When: Inference failed for an unspecified reason (sanitized upstream error).

Resolution: Retry the request. If the issue persists, report error.request_id to Support.

INTERNAL_ERROR — 500

When: An unexpected error occurred in the Skytells gateway.

Resolution: Retry the request. If it persists for more than a few minutes, check status.skytells.ai and report error.request_id to Support.

Safety & Policy

CONTENT_POLICY_VIOLATION — 422

When: The request was blocked by Skytells' safety or content policy.

Resolution: Modify or rephrase the prompt. Do not retry with the same content. See Responsible AI.

Retry Guidance

Handling Errors in Code

from openai import OpenAI, APIStatusError

client = OpenAI(
    api_key="YOUR_SKYTELLS_API_KEY",
    base_url="https://api.skytells.ai/v1",
)

try:
    response = client.chat.completions.create(
        model="deepbrain-router",
        messages=[{"role": "user", "content": "Hello!"}],
    )
    print(response.choices[0].message.content)

except APIStatusError as e:
    body = e.response.json().get("error", {})
    error_id = body.get("error_id")
    request_id = body.get("request_id")

    if error_id == "INSUFFICIENT_CREDITS":
        print("Top up your balance at console.skytells.ai/billing")
    elif error_id == "RATE_LIMITED":
        # implement exponential backoff
        import time; time.sleep(2)
    elif error_id in ("INFERENCE_ERROR", "INTERNAL_ERROR"):
        print(f"Transient error — retry. request_id={request_id}")
    elif error_id == "CONTENT_POLICY_VIOLATION":
        print("Content blocked — modify your prompt")
    else:
        print(f"Unhandled error: {error_id} — {body.get('message')}")