Overview

Errors

When an API request fails, the Skytells API always returns a structured JSON body with a machine-readable error_id and a human-readable message:

{
  "error_id": "MODEL_NOT_FOUND",
  "message": "The model with slug 'example' does not exist"
}

Errors are grouped into two levels depending on where the problem happens:

API-level errors happen before a prediction starts. These are related to the request itself or to API access, such as invalid input, missing parameters, authentication failures, or permission issues.

Prediction-level errors happen after the API has already accepted your request and started running the model. In this case, the request was valid, but something went wrong during inference or model execution.

Error Levels

Error Levels Flow

To make it easier to understand, here is a flow diagram of the error levels:

API Level Error Flow

Here's the flow of an API level error when the request is invalid:

At this error layer, your request is not yet queued to be served in our prediction serving infrastructure.

Prediction Level Error Flow

Here's the flow of a prediction level error when the model inference fails:

At this error layer, your request was queued to be served in our prediction serving infrastructure, but the model inference failed. Please also note that Safety Controls are applied at this layer as well, so if the model inference fails due to a safety violation, the prediction will be failed and the error will be returned to you.

Learn more about Prediction Level Errors.

Error Resources

API Level Errors

API level errors are errors that happen before the request is queued to be served in our prediction serving infrastructure.

400 — Bad Request / Infrastructure Errors

The request was malformed or contained invalid input.

Sometimes Skytells performs pre-checks on the request before it is queued to be served in our prediction serving infrastructure, In case of INFRASTRUCTURE_ERROR, please take a look at the Prediction Level Errors for more details on the prediction level errors.

401 — Unauthorized

Authentication failed or the account is not permitted to make requests.

402 — Payment Required

The account balance or credits are insufficient to complete the request.

403 — Forbidden

The request was understood but refused.

404 — Not Found

The requested resource does not exist.

409 — Conflict

The request conflicts with the current state of a resource.

422 — Unprocessable Entity

The request was well-formed but was unable to be followed due to semantic errors.

Also, If your prediction got returned with a status: failed and an error field, it means that the prediction level error occurred.

{
  "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",
}

It could be due to the following reasons:

• The model could not produce output from the given prompt or input parameters.
• Safety Controls triggered.
• The model is currently unavailable.
• The model is not authorized to be used.
• Error at the edge of the model serving infrastructure.

429 — Too Many Requests

You have exceeded the allowed request rate.

451 — Unavailable For Legal Reasons

The request was refused due to legal reasons.

When you encounter this error, please contact support.

500 — Internal Server Error

An unexpected error occurred on the Skytells backend.

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 { error_id, message } = await res.json();
  switch (error_id) {
    case 'INSUFFICIENT_CREDITS':
      // redirect to billing
      break;
    case 'RATE_LIMIT_EXCEEDED':
      // implement backoff
      break;
    default:
      console.error(error_id, message);
  }
}

Related

• Prediction Errors — Prediction-level error codes and troubleshooting
• Rate Limits — Rate limiting behavior and retry strategies
• Inference API Errors — OpenAI-compatible error schema
• 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