Error Handling

HTTP status codes and error responses

HTTP Status Codes

The API uses conventional HTTP response codes to indicate success or failure.

200 OK

Request succeeded

201 Created

Resource successfully created

400 Bad Request

Invalid request data

401 Unauthorized

Invalid or missing API key

403 Forbidden

API key lacks required scope or plan limit exceeded

404 Not Found

Resource not found

429 Too Many Requests

Rate limit exceeded

500 Server Error

Something went wrong on our end

Error Response Format

{
  "success": false,
  "error": {
    "message": "Invalid API key",
    "code": "UNAUTHORIZED"
  }
}

Common Error Codes

UNAUTHORIZED

The API key is invalid or missing

FORBIDDEN

The API key doesn't have the required scope

VALIDATION_ERROR

The request body contains invalid data

NOT_FOUND

The requested resource doesn't exist

PLAN_LIMIT_EXCEEDED

You've exceeded your plan's limits

RATE_LIMIT_EXCEEDED

Too many requests, try again later