API Error Reference

Error Codes & Handling

Complete reference for API error codes, formats, and best practices for error handling.

Error Response Format

Error Response Example

{
  "error": {
    "type": "validation_error",
    "code": "INVALID_FIELD",
    "message": "The 'email' field must be a valid email address.",
    "field": "email",
    "request_id": "req_abc123xyz"
  }
}

HTTP Status Codes

400

Bad Request

The request is malformed or missing required parameters.

401

Unauthorized

Missing or invalid API key. Check your Authorization header.

403

Forbidden

Your API key doesn't have permission for this action.

404

Not Found

The requested resource doesn't exist.

409

Conflict

The resource already exists or is in a conflicting state.

422

Validation Error

One or more request fields failed validation.

429

Rate Limited

Too many requests. Check the retry_after header.

500

Server Error

An unexpected error occurred. Contact support if persistent.

Error Handling Best Practices

Include request_id — Always log the request_id for debugging and support tickets.
Implement retry logic — Retry 5xx errors with exponential backoff (max 3 attempts).
Log errors properly — Log error type, code, message, and timestamp for debugging.
User-friendly messages — Don't show raw API errors to users. Map them to friendly messages.

Need Help Debugging?

Check the API docs or contact our developer support team.

API Documentation Contact Support