Error response shape

All errors return a consistent JSON body:

{
  "success": false,
  "error": {
    "message": "Human-readable description",
    "code": "ERROR_CODE"
  }
}

HTTP status codes

Status	Meaning
200	Success
400	Bad request — invalid input (see message for details)
401	Unauthorized — missing or invalid API key
402	Insufficient credits
403	Forbidden — endpoint requires a higher plan
404	Profile not found
422	Validation error — request body failed validation
429	Rate limit exceeded
500	Server error

Common errors

Invalid API key

HTTP/1.1 401 Unauthorized

{
  "error": { "message": "Invalid or revoked API key" }
}

Insufficient credits

HTTP/1.1 402 Payment Required

{
  "error": { "message": "Insufficient credits. Required: 5, available: 2" }
}

Rate limit exceeded

HTTP/1.1 429 Too Many Requests

{
  "error": { "message": "Rate limit exceeded. Try again in 8 seconds." }
}

Validation error

HTTP/1.1 422 Unprocessable Entity

{
  "error": {
    "message": "Validation failed",
    "details": ["profileId must be a MongoDB ObjectId"]
  }
}

Rate limit headers

Every response includes:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1716700860

X-RateLimit-Reset is a Unix timestamp indicating when the window resets.

Retrying

For 429 responses, wait until X-RateLimit-Reset before retrying. For 500 errors, use exponential backoff starting at 1 second.