API Error Handling

Errors

When a request fails, Skytells returns structured JSON so you can branch on stable error_id values (not on human-readable messages).

Which shape you get depends on the route:

• Simple / unified REST body — error_id and message (and related fields). See Simple API error body.
• Inference routes (Chat, Responses, Embeddings) — a different top-level layout; no unified status / response wrapper. See Inference error response.
• Predictions — may use the structured envelope. Full field definitions: Error objects.

Two error levels

Errors fall into two buckets: problems with the request or access (API-level), or problems while running the model after the job was accepted (prediction-level).

How the two levels differ in practice

API-level: Your request fails validation or policy before anything is queued to prediction serving.

Prediction-level: Validation passed; the job was queued and ran in serving, but inference failed. For predictions, the HTTP status on GET can still be 200 OK while the JSON body shows status: "failed" and an error message.

Safety controls apply during serving; a policy violation can surface as a failed prediction with an error string.

Learn more: Prediction-level errors.

Error shapes

Skytells returns different JSON shapes depending on the API surface:

Unified REST (API-level example) — returned before a prediction is queued:

{
  "status": false,
  "response": "short summary",
  "error": { "http_status": http_status_code, "message": "human-readable reason", "details": "extra context", "error_id": "error_code_value" }
}

Inference — nested error object (serving or generation failure after the request reaches inference infrastructure):

{
  "error": { "http_status": http_status_code, "message": "human-readable reason", "details": "extra context", "error_id": "error_code_value" }
}

This covers cases where the language model fails to produce output, parameters are wrong for the model, or the model is not authorized — see Inference errors.

Failed prediction — job was accepted and reached a terminal failed state:

{
  "status": "failed",
  "error": "Failed to generate image / video / audio ..etc.",
  "output": null,
  "data_removed": true,
  "metrics": {
    "predict_time": 1.082823234,
    "total_time": 1.094474004
  },
  "model": "truefusion",
  "source": "api"
}

The full prediction object can include additional fields; see Error objects.

HTTP status codes (quick reference)

• Inference errors — Chat, Responses, Embeddings: error_id catalog and HTTP behavior.
• Prediction errors — Predictions routes, HTTP codes per error_id, and status: "failed" on the prediction resource.

Where in the pipeline did it fail?

Error resources

API-level errors

These occur before the request is queued to prediction serving.

400 — Bad Request / infrastructure

The request was malformed or invalid.

For Inference-specific validation errors, see Inference API errors.

401 — Unauthorized

Authentication failed or the account cannot make requests.

402 — Payment required

Insufficient balance or credits for the operation.

403 — Forbidden

The request was understood but refused.

404 — Not found

The requested resource does not exist.

Note: Predictions GET /v1/predictions/{uuid} does not return 404 for a missing prediction. Use 502 with an error_id in the structured envelope — Prediction errors — Get one.

409 — Conflict

The request conflicts with the current state of a resource.

422 — Unprocessable entity

The body was well-formed but could not be applied (semantic or policy failure).

If the prediction returns status: "failed" with an error field, inference failed after the job was accepted. Shape: failed prediction object. Details: Prediction errors — Prediction-level errors.

Common causes:

• The model could not produce output from the given prompt or parameters.
• Safety controls triggered.
• The model is temporarily unavailable.
• The model is not authorized for this request.
• An error at the edge of model serving.

429 — Too many requests

You exceeded a gateway or API-surface limit for your account. Limits apply per account (across API keys) and may be scoped by model, time window, tokens, and route — not one global counter.

Typical causes: burst traffic, tight polling on GET endpoints, or high concurrency on the same model.

See Account tiers for plan ceilings, and Rate limits for x-skytells-ratelimit-* headers and backoff.

Example body (shape may vary slightly by endpoint):

{
  "error_id": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests. Please wait before retrying."
}

Response headers

451 — Unavailable for legal reasons

The request was refused due to legal reasons.

When you encounter this error, contact support.

500 — Internal server error

An unexpected error occurred on the Skytells backend.

502 — Bad gateway

The prediction serving layer returned an error while running or loading a prediction, or access was denied for a private resource. Responses use the unified API error envelope with HTTP 502 and a stable error_id.

503 — Service unavailable

Temporary overload or an empty handler result on Predictions create (e.g. PREDICTION_ERROR). Often safe to retry with backoff.

Resolution: Prediction errors — PREDICTION_ERROR.

Handling errors in code

const res = await fetch('https://api.skytells.ai/v1/predictions', {
  method: 'POST',
  headers: {
    'x-api-key': YOUR_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ model: 'skytells/truefusion-pro', input: { prompt: '...' } }),
});

if (!res.ok) {
  const body = await res.json();
  const err = body.error;
  const error_id = err?.error_id;
  const message = err?.message;
  switch (error_id) {
    case 'INSUFFICIENT_CREDITS':
      // redirect to billing
      break;
    case 'RATE_LIMIT_EXCEEDED':
      // implement backoff
      break;
    default:
      console.error(error_id, message);
  }
}

Error response shapes

Canonical JSON for Inference ({ "error": { ... } }) and unified REST (status, response, error) is on Error objects — Inference error response and Predictions API structured error. Per-error_id behavior for Inference: Inference API errors.

Related

• Error objects — Linkable error JSON shapes (simple body, Inference, Predictions)
• Prediction errors — Predictions API error codes and troubleshooting
• Rate limits — Gateway headers, Retry-After, and backoff
• Inference API errors — error_id catalog, resolutions, and code samples
• TypeScript SDK Error Handling — SkytellsError class and SDK error handling patterns
• TypeScript SDK Reliability — Automatic retries and timeout configuration
• Predictions API — Creating and managing predictions
• Models API — Model discovery and schemas
• Responsible AI — Content safety policies