Errors

In this guide, we will talk about what happens when something goes wrong while you work with the API. Mistakes happen, and we'll help you understand how to identify and resolve issues when they occur. Let's look at some status codes and error types you might encounter.

You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the error type and error message to figure out what has gone wrong and do some rudimentary debugging (before contacting support).

Before reaching out to support with an error, please be aware that most reported errors are typically related to client-side issues. Therefore, please carefully check your code and error messages before contacting Skytells support.

Status codes

Here is a list of the different categories of status codes returned by the Skytells API. Use these to understand if a request was successful.

Name
200
Description
A 200 status code indicates a successful response.
Name
400
Description
A 400 status code indicates a client error — this means it's likely an issue with your request.
Name
422
Description
A 422 status code indicates a client error — this means it's likely an issue with your request.
Name
500
Description
A 500 status code indicates a server error — if you encounter these, please contact support.

Error types

Whenever a request is unsuccessful, the Skytells API will return an error response with an error type and message. You can use this information to understand better what has gone wrong and how to fix it. Most of the error messages are pretty helpful and actionable.

Errors are returned as JSON objects with an error property, which is an object with the following properties:

message - A human-readable error message.
error_id - The type of error that occurred.
http_status - The HTTP status code of the response.
details - Additional details about the error (when available).

Here is a list of the common error types you might encounter with the Skytells API:

Name
VALIDATION_ERROR
Description
Returned when the request validation fails with detailed error messages.
Name
MODEL_NOT_FOUND
Description
Returned when the requested model does not exist or you don't have access to it.
Name
MODEL_NOT_ACTIVE
Description
Returned when the requested model is not currently active.
Name
INSUFFICIENT_CREDITS
Description
Returned when you don't have enough credits for the requested operation.
Name
PREDICTION_FAILED
Description
Returned when the prediction process fails with detailed error messages.
Name
UNAUTHORIZED
Description
Returned when authentication fails or is missing.
Name
PREDICTION_NOT_FOUND
Description
Returned when the requested prediction doesn't exist or you don't have access to it.

Error response

{
  "error": {
    "http_status": 422,
    "message": "Invalid input parameters",
    "details": "The 'prompt' field is required",
    "error_id": "VALIDATION_ERROR"
  }
}

Credit error example

{
  "error": {
    "http_status": 400,
    "message": "User has 5 credits, but 10 are required",
    "error_id": "INSUFFICIENT_CREDITS"
  }
}

Authentication error

{
  "error": {
    "http_status": 401,
    "message": "Invalid or missing API key",
    "details": "Please obtain a valid API key from the dashboard",
    "error_id": "UNAUTHORIZED"
  }
}

Error IDs

Below is the complete reference of all error IDs returned by the Skytells API. Use the error_id field in error responses to handle specific errors programmatically.

Error ID	HTTP Status	Description
`UNAUTHORIZED`	401	Invalid or missing API key
`VALIDATION_ERROR`	400 / 422	Request parameters failed validation
`INVALID_PARAMETER`	400	Invalid request parameter
`INVALID_INPUT`	400	Invalid model input
`INVALID_DATE_FORMAT`	400	Date parameter is not a valid `YYYY-MM-DD`
`INVALID_DATE_RANGE`	400	`from` date is after `to` date
`MODEL_NOT_FOUND`	404	Model slug not found
`MODEL_NOT_ACTIVE`	400	Model is not currently active
`INSUFFICIENT_CREDITS`	402	Not enough credits for the operation
`PAYMENT_REQUIRED`	402	Payment required to proceed
`ACCOUNT_SUSPENDED`	403	Account has been suspended
`SECURITY_VIOLATION`	403	Content policy violation
`RATE_LIMIT_EXCEEDED`	429	Too many requests — slow down
`PREDICTION_FAILED`	—	Prediction completed with a failure status
`PREDICTION_NOT_FOUND`	404	Prediction does not exist or is inaccessible
`INTERNAL_ERROR`	500	Server error — contact support if persistent
`SERVER_ERROR`	—	Non-JSON response from server
`INVALID_JSON`	—	Server returned invalid JSON
`WAIT_TIMEOUT`	408	Polling exceeded the configured `maxWait`
`REQUEST_TIMEOUT`	—	HTTP request timed out
`NETWORK_ERROR`	—	Connection issue (DNS, socket, etc.)

Error IDs without an HTTP status (marked —) are raised client-side by the SDKs and do not correspond to an API response.

Error Handling Best Practices

When working with the Skytells API, we recommend implementing the following error handling best practices:

Implement retries: Use exponential backoff for temporary failures (e.g., rate limits)
Validate inputs: Check input parameters against model constraints before submitting
Handle specific errors: Implement specific handling for each error type
Log errors: Maintain detailed logs of API errors for troubleshooting
User feedback: Translate API errors into user-friendly messages in your UI

All error responses include an error_id and a descriptive message field to help you troubleshoot issues. Always implement error handling for these scenarios in your client applications.

Service Status

Before diving into debugging, always check the Skytells service status page first. This simple step can save hours of engineering time — what may appear to be a bug in your code could be a temporary platform issue.

At Skytells, we maintain an extremely high SLA. If you're experiencing unexpected errors or timeouts, check status.skytells.ai before investigating further — it could save you significant debugging time.

Check Service Status

The status page provides real-time information on:

API availability — current uptime and response times
Scheduled maintenance — planned downtime windows
Incident history — past incidents and resolutions
Component status — individual service health (API, GPU workers, webhooks, etc.)

If the status page shows all systems operational and you're still encountering issues, proceed with the error handling guidance above or contact support.