Errors

Errors are returned as a unified JSON envelope with a machine-readable code, a human-readable message, and a unique request id.

Envelope

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": {
    "code": "validation_error",
    "message": "plan_id is required",
    "field": "plan_id"
  },
  "request_id": "req_AbCdEf..."
}

error.code — stable across versions; use it in application logic.
error.message — human-readable message for display or logs (may change).
error.field — present on validation_error only; points to the offending field.
request_id — include it when contacting support so we can trace the request.

Success code reference

Code	HTTP	Description
`ok`	200	Request succeeded and the response body contains the result.
`created`	201	Resource was created successfully; the response includes the new object.
`accepted`	202	Request was accepted for asynchronous processing.
`no_content`	204	Request succeeded and there is no response body to return.

Error code reference

Code	HTTP	Description
`missing_api_key`	401	Authorization header was not provided.
`invalid_api_key`	401	API key is invalid or unknown.
`revoked_api_key`	401	API key has been revoked from the portal.
`forbidden`	403	Key is valid but not allowed to access this resource.
`not_found`	404	Requested id does not exist on your account.
`method_not_allowed`	405	HTTP method is not supported on this path.
`idempotency_conflict`	409	Idempotency-Key was reused with a different request body.
`insufficient_funds`	402	Wallet balance is not enough to issue this order.
`plan_unavailable`	422	Plan is currently unavailable or not enabled for your account.
`validation_error`	422	Request body is missing fields or wrongly shaped.
`rate_limited`	429	You exceeded the allowed rate (default 60 req/min per key).
`internal_error`	500	Internal error. Retry with backoff and include request_id when reporting.
`upstream_unavailable`	503	Backend provider temporarily unavailable — retry after a short delay.

Retry strategy

Retry: 429, 500, 502, 503, 504 with exponential backoff (1s, 2s, 4s, 8s).
Do not retry: other 4xx — fix the request first.
When retrying a POST, reuse the same Idempotency-Key to avoid duplicates.