Error Codes & Troubleshooting

Learn about common API errors, their causes, and how to resolve them. Use this guide to debug issues and implement robust error handling in your applications.

Quick Reference — All Error Codes

Status Name Severity One-line description
200 OK Info Request succeeded and response is ready.
401 Unauthorized Error Missing, invalid, or expired API key.
402 Payment Required Error Insufficient credits to complete the request.
403 Forbidden Warning Authenticated but insufficient permissions.
404 Not Found Warning Model not found or incorrect API path.
422 Unprocessable Entity Warning Validation failed — missing or invalid fields.
429 Too Many Requests Error Rate limit exceeded, wait for retry_after seconds.
500 Internal Server Error Critical Unexpected server error, retry with backoff.

Error Response Structure

When the LLM Resayil API encounters an error, it returns a JSON response describing what went wrong. Understanding how to parse these responses is essential for building robust error handling in your applications.

All error responses follow this unified format:

JSON
{ "error": { "message": "Human-readable error message", "code": 401 } }

Certain errors — such as validation errors (422) — include an additional errors object with per-field validation details:

JSON — 422 Validation
{ "error": { "message": "Validation failed", "code": 422 }, "errors": { "model": ["The model field is required."], "messages": ["The messages field must be an array."] } }

Detailed Error Response Examples

401 Unauthorized Error

Missing or invalid API key in the Authorization header.

HTTP / JSON — 401
HTTP/1.1 401 Unauthorized { "error": { "message": "Unauthenticated.", "code": 401 } }
  • Verify the API key is correct — copy it from the dashboard with no extra spaces
  • Ensure the Authorization header format is: Authorization: Bearer YOUR_KEY
  • Generate a new key if you suspect the current one is compromised
  • Confirm the key has not been revoked from the dashboard
402 Payment Required Error

Your credit balance has been exhausted. You must top up to continue making API calls.

HTTP / JSON — 402
HTTP/1.1 402 Payment Required { "error": { "message": "Insufficient credits. Please top up your balance to continue.", "code": 402 } }
  • Go to the dashboard and purchase additional credits at /billing/plans
  • Check your current balance via the GET /api/billing/subscription endpoint
  • Consider upgrading to a subscription plan to avoid service interruptions
403 Forbidden Warning

Authenticated but the account does not have sufficient permissions to access the requested resource.

HTTP / JSON — 403
HTTP/1.1 403 Forbidden { "error": { "message": "You do not have permission to access this resource.", "code": 403 } }
  • Check your account status in the dashboard — it may be suspended
  • Confirm your subscription is still active
  • Contact support if you believe this is an error
404 Not Found Warning

The requested model does not exist, or the API path is incorrect.

HTTP / JSON — 404
HTTP/1.1 404 Not Found { "error": { "message": "Model not found.", "code": 404 } }
  • Verify the model name used in the model field of your request
  • Review the list of available models in your dashboard
  • Confirm the request URL is correct
422 Unprocessable Entity Warning

Request validation failed. The response includes an errors object describing each invalid field.

HTTP / JSON — 422
HTTP/1.1 422 Unprocessable Entity { "error": { "message": "Validation failed", "code": 422 }, "errors": { "model": ["The model field is required."], "messages": ["The messages field must be an array."] } }
  • Inspect the errors object to identify the problematic fields
  • Ensure all required fields are included: model and messages
  • Confirm messages is an array of objects with role and content
  • Validate your JSON syntax before sending
429 Too Many Requests Error

You have exceeded your rate limit. The response includes a retry_after field indicating how many seconds to wait before retrying.

HTTP / JSON — 429
HTTP/1.1 429 Too Many Requests X-RateLimit-Limit: 20 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1741305600 { "error": { "message": "Rate limit exceeded", "code": 429 }, "retry_after": 45 }
  • Wait the number of seconds specified in retry_after before retrying
  • Implement exponential backoff for automatic retries
  • Check your tier's rate limits and consider upgrading if you frequently hit this error
  • Implement client-side rate limiting to stay within your quota
500 Internal Server Error Critical

An unexpected server-side error occurred. These are rare and usually temporary.

HTTP / JSON — 500
HTTP/1.1 500 Internal Server Error { "error": { "message": "An unexpected error occurred. Please try again later.", "code": 500 } }
  • Retry the request after a few seconds
  • Implement exponential backoff for automatic retries
  • If the error persists, contact support

Debugging Checklist

When you encounter an error, work through this checklist to identify and resolve the issue:

For All Errors

  • Check your API key is correct and properly formatted in the Authorization header
  • Ensure you are using the POST method, not GET
  • Verify the Content-Type header is set to application/json
  • Check that your request JSON is valid with no syntax errors

For 401 and 403 Errors

  • Verify your account is active and not suspended
  • Check that your API key has not been revoked
  • Ensure your subscription tier is active
  • Confirm you have enough credits (see 402)

For 422 Errors

  • Include all required fields: model and messages
  • Verify the model name is valid and available in your account
  • Ensure messages is an array of objects with role and content properties
  • Use the errors object in the response to identify the problematic field

For 429 Errors

  • Check the X-RateLimit-Remaining header in your responses
  • Implement retry logic with exponential backoff
  • Reduce the frequency of your requests
  • Consider upgrading to a higher tier for increased limits

For 500 Errors

  • Retry the request after 5–10 seconds
  • Implement exponential backoff for multiple retries
  • Contact support if errors persist

Error Handling Best Practices

1. Always Parse Error Responses

Do not just check the HTTP status code. Parse the error response JSON to understand what went wrong and provide meaningful feedback to your users.

2. Implement Retry Logic

Use exponential backoff with jitter for retryable errors (429, 500). See the Rate Limits guide for implementation details.

3. Log Errors for Debugging

Log full error responses including status codes, error codes, and request IDs. This makes debugging significantly faster.

4. Provide User-Friendly Messages

Do not expose raw error messages to users. Map error codes to friendly messages and provide actionable guidance.

5. Monitor Rate Limits Proactively

Check X-RateLimit-Remaining in responses and throttle requests before hitting the limit.

6. Set Appropriate Timeouts

Set request timeouts to at least 30 seconds to allow for slower models and network latency.

Related Resources

Done with documentation?

Ready to start building with LLM Resayil.

Create Free Account →