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 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.