Errors

The Vexrail API uses standard HTTP status codes to indicate the success or failure of a request. Error responses include a JSON body with details about what went wrong.

Error Response Format

{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}

Field	Description
statusCode	The HTTP status code.
message	A human-readable description of the error.
error	The HTTP status text.

HTTP Status Codes

Client Errors (4xx)

Status	Meaning	Common Causes
400 Bad Request	The request body is invalid or missing required fields.	Missing model field, empty messages array, invalid JSON.
401 Unauthorized	Authentication failed.	Missing or invalid x-publishable-key or x-secret-key, key pair mismatch, inactive key.
403 Forbidden	Access denied.	Domain not verified, insufficient credit balance.
404 Not Found	The requested resource does not exist.	Invalid conversation ID, invalid endpoint path.
422 Unprocessable Entity	The request was well-formed but contains semantic errors.	Invalid model name, invalid parameter values.

Server Errors (5xx)

Status	Meaning	Action
500 Internal Server Error	An unexpected error occurred on the server.	Retry the request. If the issue persists, contact support.
502 Bad Gateway	The upstream LLM provider returned an error.	Retry the request. The LLM provider may be experiencing issues.
503 Service Unavailable	The service is temporarily unavailable.	Retry with exponential backoff.

Common Error Scenarios

Missing API Keys

# Request without authentication headers
curl -X POST https://api.vexrail.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}'

Response: 401 Unauthorized

Fix: Include both x-publishable-key and x-secret-key headers.

Domain Not Verified

Response: 403 Forbidden

Fix: Complete domain verification for your project.

Insufficient Credits

Response: 403 Forbidden

Fix: Add funds to your credit wallet.

Invalid Model

Response: 400 Bad Request or 422 Unprocessable Entity

Fix: Use the models endpoint to get a list of available models.

Retry Strategy

For 5xx errors and network failures, we recommend implementing exponential backoff:

1. Wait 1 second, then retry.
2. If it fails again, wait 2 seconds, then retry.
3. If it fails again, wait 4 seconds, then retry.
4. Continue doubling the wait time up to a maximum of 60 seconds.
5. After a reasonable number of retries (e.g., 5), stop retrying and log the error.

async function withRetry(fn: () => Promise<any>, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      if (error.status && error.status < 500) throw error; // Don't retry client errors
      const delay = Math.min(1000 * Math.pow(2, attempt), 60000);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

Getting Help

If you encounter persistent errors that you cannot resolve, contact support with:

• The full error response (status code and message).
• The request you were making (with sensitive data like API keys redacted).
• The timestamp of when the error occurred.