Errors

The API uses standard HTTP status codes to signal the outcome of a request, and every error returns the same JSON envelope so you can handle failures consistently.

HTTP status codes

Status	Meaning
2xx	Success.
400	Bad request — the data was unacceptable, usually a missing or invalid parameter. The data field identifies the offending field.
401	Unauthorized — the API key is missing or invalid.
403	Forbidden — the API key is valid but lacks permission for this route.
404	Not found — the endpoint or resource does not exist.
5xx	A server-side problem. Safe to retry with backoff.

Error envelope

Every error response has the same shape:

{
  "code": "DATA.INVALID_NAME",
  "ns": "DATA",
  "message": "The provided name is invalid.",
  "status": 400,
  "data": { "field": "name" }
}

Field	Type	Description
code	string	Stable, namespaced identifier (NAMESPACE.IDENTIFIER). Use this for programmatic handling.
ns	string	The error namespace — the part before the dot (for example DATA).
message	string	Human-readable description, suitable for display.
status	integer	The HTTP status code, repeated in the body.
data	object	Optional context. For validation errors it carries the offending field.

Handling errors

• Branch on the HTTP status for the broad category (client error vs server error).
• Use the stable code rather than the message for programmatic decisions — messages may change, codes do not.
• On a 400, read data.field to point the user at the input that needs fixing.
• Retry 5xx responses with exponential backoff; do not blindly retry 4xx responses without changing the request.