Error Codes

All errors are returned in the standard envelope with error.code (an English slug) and error.message (human-readable). The code (slug) is stable for programmatic checks; the message text may change.

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Input validation failed.",
    "details": { "field": "period" }
  },
  "meta": { "trace_id": "...", "timestamp": "..." }
}

Generic HTTP Errors

HTTP	code	Meaning
400	invalid_input	Invalid or missing input
400	missing_idempotency_key	Required Idempotency-Key header is missing
401	unauthorized	Authentication failed (missing/invalid key or secret)
403	forbidden	Not authorized (e.g. you do not own the service)
404	not_found	Resource not found
405	method_not_allowed	HTTP method not supported on this endpoint
409	conflict	Conflicting request (e.g. downgrade attempt)
422	validation_error	Business rule validation failed
429	rate_limited	Request limit exceeded (see Rate Limiting)
500	internal_error	Unexpected server-side error

Domain Errors

HTTP	code	Meaning
402/422	insufficient_credit	Credit balance insufficient for the operation
422	idempotency_key_reuse	Same Idempotency-Key used with a different body
422	location_locked	Location cannot be changed during an upgrade
404	webhook_not_found	Webhook endpoint record not found
409	webhook_limit_exceeded	Maximum active webhooks per reseller exceeded

How To Handle

• Always check error.code programmatically, not the message text.
• Retrying makes sense for 5xx and 429; do not retry 4xx errors (except 429) without fixing the request.
• When contacting support, share the meta.trace_id value — it lets us find the related request in server logs.