Errors

All error responses follow a consistent format with an error message and machine-readable error code.

Error Format

Error Response

{
  "error": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE",
  "details": {}  // Optional additional context
}

HTTP	Code	Description
400	VALIDATION_ERROR	Invalid request parameters
400	CONTENT_BLOCKED	Content violates policy
401	UNAUTHORIZED	Missing or invalid API key
402	NO_CREDITS	Insufficient credits for this action
403	FORBIDDEN	No permission for this resource
404	NOT_FOUND	Resource not found
429	RATE_LIMITED	Too many requests
500	INTERNAL_ERROR	Unexpected server error

402 No Credits

{
  "error": "Insufficient credits",
  "code": "NO_CREDITS",
  "details": {
    "needsProfile": false
  }
}

400 Validation Error

{
  "error": "Character ID is required",
  "code": "VALIDATION_ERROR",
  "details": {
    "field": "characterId"
  }
}

Always check the HTTP status code first, then the code field for specific error handling
Implement exponential backoff for 429 rate limit errors
For 402 errors, prompt users to purchase more credits
Log 500 errors and report them — they indicate a bug on our end