Prediction API Errors

Prediction errors

This page is the Predictions supplement to API errors (HTTP semantics, 401–429, shared error_id tables, and handling patterns). It lists GET /v1/predictions, POST /v1/predict, POST /v1/predictions, and GET /v1/predictions/:uuid only.

Also read: HTTP status · 401 · 402 · 403 · 404 · 422 · 429 · 500 · 502 · 503

Inference routes use a different shape — Inference errors. JSON field lists — Error objects.

Predictions-only notes

404: MODEL_NOT_FOUND is for a wrong model slug on list/create. GET /v1/predictions/{uuid} does not return 404 for a missing prediction id — use 502 + error_id (Get one).

Error response format

Structured failures use the unified API error envelope (status: false, response, nested error). The response HTTP status matches error.http_status. Branch on error.error_id.

{
  "status": false,
  "response": "Human-readable summary",
  "error": {
    "http_status": 402,
    "message": "Detailed message",
    "details": "String or object",
    "error_id": "ERROR_CODE"
  }
}

Examples: Error objects (VALIDATION_ERROR, 502, 402 credits).

GET /v1/predictions — list

Shared auth errors: 401 (UNAUTHORIZED, ACCOUNT_SUSPENDED).

POST /v1/predict / POST /v1/predictions — create

Same handler. Shared codes (VALIDATION_ERROR, MODEL_NOT_SUPPORTED, credits, 403 model gates): 422 · 402 · 403.

Request validation

Examples: missing model · missing input

INVALID_PARAMETER_COMBINATION — 400

Predictions-specific: query or input fields cannot be combined. Fix using error.message / error.details.

Model checks (before modality branch)

Incompatible parameters (create)

Image predictions

Video / audio predictions

GET /v1/predictions/:uuid — get one

Shared: 401.

502 example: Error objects · serving failures: 502

Retry: 500 with backoff. 502: branch on error_id — ACCESS_DENIED is not retryable; other codes per Prediction Serving Error — 502.

ACCESS_DENIED — 502

Not allowed to use this model, read this prediction, or access this resource (private, non-sharable, or another account). Do not retry until access is valid.

VALIDATION_ERROR — 422

Create body missing model or input. 422 · JSON: validation example

Prediction Serving Error — 502

Serving/runtime failure with 502 and error.error_id. 502 — Bad Gateway · 502 envelope

Prediction-level errors

After the job is accepted, status: "failed" and error on the prediction resource (often 200 on GET) — not the structured error envelope. API errors — prediction level · failed prediction object · prediction.failed webhook

{
  "status": "failed",
  "error": "Failed to generate image.",
  "output": null,
  "id": "pred_id....",
  "model": "truefusion"
}

Trailing slash

POST /v1/predictions/ may redirect to GET the list. Use /v1/predictions without a trailing slash.

Handling errors

Use the envelope: read error.error_id on the JSON body (body.error in most clients). Nested shape matches Error objects. General patterns: Handling errors in code.

import os, requests

r = requests.post(
    "https://api.skytells.ai/v1/predictions",
    headers={
        "x-api-key": os.environ["SKYTELLS_API_KEY"],
        "Content-Type": "application/json",
    },
    json={"model": "your-model-slug", "input": {}},
)
data = r.json()
err = data.get("error") or {}
if r.status_code >= 400 and err.get("error_id"):
    print(err["error_id"], err.get("message"))

Related

• API errors — shared HTTP and error_id reference
• Rate limits — 429
• status.skytells.ai — incidents