Errors

Errors follow a consistent envelope:

{
  "error": {
    "code": "invalid_request",
    "message": "request body failed validation",
    "issues": { ... }
  }
}

Common codes

HTTP	Code	Meaning
400	`invalid_request`	Body failed validation (see `issues`)
401	`unauthenticated`	Missing or invalid API key
403	`merchant_inactive`	Merchant account not active
403	`insufficient_scope`	API key missing required scope
404	`not_found`	Resource not found or belongs to another merchant
409	`conflict`	Duplicate request (idempotency in-flight)
429	`rate_limited`	Too many requests; see `Retry-After`
500	`internal_error`	Something broke on our side