Skip to main content

​
Error Response Format

All errors are returned in a standardized JSON format: 
{
  "code": 400,
  "status": "Bad Request",
  "message": "Invalid request",
  "errors": {
    "field_name": ["Error detail"]
  }
}
  • code: the HTTP status code (e.g., 400, 401, 404, etc.)
  • status: the human-readable status (e.g., Bad Request, Unauthorized)
  • message: a short summary of the error
  • errors: (optional) additional details, often related to field validation
Common Error Codes
HTTP CodeStatusDescriptionSuggested Fix
400Bad RequestThe request is invalid (missing or malformed parameters).Check your request schema and required fields.
401UnauthorizedMissing or invalid API key.Include an Authorization header with a valid API key.
403ForbiddenThe API key does not have sufficient permissions.Check your access rights or use a key with proper permissions.
404Not FoundThe requested resource does not exist.Verify the ID or resource reference.
422Unprocessable EntityThe data is syntactically correct but violates business rules.Inspect the errors object for field-specific issues.
429Too Many RequestsYou have exceeded the request limit.Wait before retrying, implement exponential backoff.
500Internal Server ErrorAn unexpected server error occurred.Retry later, contact support if the issue persists.

​
Troubleshooting

  1. Check your request format: Ensure your JSON is valid and matches the required schema.
  2. Authentication: Confirm your API key is correct and that you are using the right environment (test or production).
  3. Inspect error details: The errors object provides specific field-level feedback.
  4. Handle rate limits (429): Implement retry logic with exponential backoff.
  5. Log errors: Store error responses for debugging, but avoid logging sensitive data.
  6. Contact support if issues persist, providing:
    • the endpoint you called
    • the payload you sent
    • the full error response you received

​
Best Practices for Error Handling

  1. Implement automatic retries for transient errors (429, 500).
  2. Show clear messages to end users, while keeping detailed logs for developers.
  3. Never expose API keys or sensitive data in error messages.
  4. Test common error cases (missing fields, invalid values, etc.) during development.