Error Handling

The TranslatePlus API uses standard HTTP status codes to indicate success or failure of requests. All error messages are standardized and consistent across all endpoints.

HTTP Status Codes

Error Response Format

All error responses follow this format:

{
  "detail": "Error message describing what went wrong"
}

Common Errors

Missing API Key (403 Forbidden)

Error Message:

API key is required. Please provide X-API-KEY header.

When it occurs:

• The X-API-KEY header is missing from the request

Example Response:

{
  "detail": "API key is required. Please provide X-API-KEY header."
}

Invalid API Key (403 Forbidden)

Error Message:

Invalid API key. Please check your X-API-KEY header.

When it occurs:

• The API key provided is invalid or has been revoked

Example Response:

{
  "detail": "Invalid API key. Please check your X-API-KEY header."
}

Insufficient Credits (402 Payment Required)

Error Message:

Insufficient credits. You have {remaining} credit(s) remaining, but this request requires {required} credit(s). Please upgrade your plan to continue using the API.

When it occurs:

• Your account doesn't have enough credits for the requested operation

Example Response:

{
  "detail": "Insufficient credits. You have 5 credit(s) remaining, but this request requires 10 credit(s). Please upgrade your plan to continue using the API."
}

Rate Limit Exceeded (429 Too Many Requests)

Error Message:

Rate limit exceeded. Please try again later.

When it occurs:

• You've exceeded your rate limit for the current time period

Example Response:

{
  "detail": "Rate limit exceeded. Please try again later."
}

Best Practices

1. Always check status codes before processing responses
2. Handle errors gracefully with appropriate user feedback
3. Implement retry logic for transient errors (500, 503)
4. Monitor your credit balance to avoid 402 errors
5. Respect rate limits to avoid 429 errors