Error Handling & Automatic Retries¶

To build resilient applications, it is crucial to understand how the Voidon API handles errors. Our architecture classifies errors into two main categories: retriable and non-retriable.

Our system features automatic retry logic to manage transient errors, improving reliability and freeing developers from implementing complex failure-handling mechanisms.

Error Categories¶

Retriable Errors (Handled Automatically)¶

These errors indicate temporary issues that are not caused by a flaw in your request. Our system will automatically attempt to execute the request again when it detects one of these problems.

1. Temporary Service Unavailability¶

These errors occur due to transient issues within our infrastructure or that of an underlying provider, such as momentary overload, network timeouts, or a temporary internal server error that is being resolved.

• Voidon's Logic: When we receive one of these errors, our system automatically retries the request. Our smart logic may also reroute the request to another healthy provider or infrastructure to maximize the chance of success, ensuring the highest possible service availability.
• Common HTTP Codes: 500 Internal Server Error, 503 Service Unavailable, 504 Gateway Timeout.

2. Rate Limit Exceeded¶

This error occurs when your API key has surpassed the number of requests allowed within the given time frame for your plan.

• Voidon's Logic: If you have configured fallback API keys, our system may attempt to retry the request using a different credential. However, you should treat this error as a signal to optimize your call volume or consider a plan upgrade.
• Common HTTP Codes: 429 Too Many Requests.

Non-Retriable Errors (Require Your Action)¶

These errors indicate a fundamental problem with your request. Retrying the exact same call will always result in the same error. Therefore, Voidon does not automatically retry in these cases.

1. Client-Side Request Errors¶

The most common cause of non-retriable errors is a malformed or invalid request.

• Description: The error lies within the structure or data of your API call. Examples include:
  • Authentication Failure (AuthenticationError): The API key is invalid, has expired, or lacks the necessary permissions.
  • Invalid Request (InvalidRequestError, BadRequestError): The request body is malformed JSON, required parameters are missing, or parameters have the wrong format.
  • Resource Not Found (NotFoundError): You are trying to use a model that does not exist or is not available to your account.
  • Context Window Exceeded (ContextWindowExceededError): The input (prompt + history) is too long for the selected model.
• Action Required: You must fix your application's code to ensure the request is valid before sending it again.
• Common HTTP Codes: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found.

Here is an example of a non-retriable error response:

1
2
3
4
5
6
7
8

{
  "error": {
    "message": "Incorrect API key provided: sk-.....",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

2. Content Policy Violations¶

Your request was blocked by our safety systems because the content of the prompt violates our usage policies.

• Description: The provided input was flagged as unsafe or inappropriate.
• Action Required: You must modify the prompt's content to comply with our policies. This error cannot be overcome without changing the input.
• Common HTTP Codes: 400 Bad Request (often with a specific code in the response body).

3. Unknown or Unexpected Errors¶

In rare cases, an error may occur that does not fall into the above categories.

• Description: An unexpected issue occurred while processing your request.
• Voidon's Logic: For safety, these errors are treated as non-retriable. We recommend you log them and, if they persist, contact technical support with the details of the request.
• Common HTTP Codes: 500 Internal Server Error (with a generic error message).