Error Codes Reference
Understanding HTTP status codes and how to handle them
2xx Success
The request was successful and the response contains the requested data.
Common with: GET, POST, PUT requests
A new resource was successfully created.
Common with: POST requests for creating resources
4xx Client Errors
The request was malformed or contains invalid parameters.
Common causes: Missing required fields, invalid JSON, incorrect data types
Authentication is required or has failed. Your API key may be missing or invalid.
Common causes: Missing API key, invalid API key, expired key
You don't have permission to access this resource. Your API key may lack the required permissions.
Common causes: Insufficient permissions, suspended account, accessing test endpoint with live key
The requested resource doesn't exist. Check your endpoint URL.
Common causes: Incorrect URL, typo in endpoint path, resource was deleted
The request was well-formed but contains semantic errors or validation failures.
Common causes: Invalid email format, out-of-range values, business logic validation failures
You've exceeded your rate limit. Wait before making more requests or upgrade your plan.
Common causes: Too many requests per minute, exceeded daily quota
5xx Server Errors
An unexpected error occurred on our servers. This is a temporary issue.
Action: Retry the request. If the issue persists, contact support.
The gateway received an invalid response from the backend server.
Action: Retry the request after a brief delay.
The service is temporarily unavailable, usually due to maintenance or overload.
Action: Check our status page and retry after a delay.
The gateway didn't receive a response from the backend server in time.
Action: Retry the request. Consider implementing exponential backoff.
Best Practices for Error Handling
- β Always check the status code before processing the response
- β Implement exponential backoff for retry logic on 5xx errors
- β Log error details for debugging but never expose sensitive data
- β Handle rate limits gracefully by respecting retry-after headers
- β Show user-friendly error messages instead of raw API responses
Need help troubleshooting?