Errors

Error response format

All errors follow a consistent JSON shape:

{
  "error": true,
  "type": "general",
  "code": 1234,
  "message": "Human-readable description",
  "payload": null
}

Field	Type	Description
error	boolean	Always true for error responses
type	string	general, auth, or system
code	number	Machine-readable error code
message	string	Human-readable description
payload	null	Always null on errors

Error types

Type	HTTP Status	When
auth	401	Invalid or missing API key
general	400 / 404	Validation failure, resource not found
system	500	Internal server error

Common error codes

Code	Type	Description
1001	auth	Invalid or expired API key
1002	general	Validation failed — check request parameters
1003	general	Resource not found
1004	general	Rate limit exceeded
1005	system	Internal server error — retry with backoff

HTTP status codes

Status	Meaning
200	Success
400	Bad request — validation error
401	Unauthorized — invalid API key
404	Not found
429	Rate limit exceeded
500	Internal server error