Errors

Audience: Developer

Standard Error Shape (Most APIs)

Most merchant/public endpoints return:

{
  "error": "human readable message",
  "code": "machine_code",
  "details": null
}

OAuth endpoints use OAuth-style error bodies:

{
  "error": "invalid_client",
  "error_description": "invalid client credentials"
}

Status	Meaning
`400`	Invalid input, invalid mode, unsupported parameter
`401`	Missing/invalid auth token
`403`	Authenticated but not allowed (scope/role/mode mismatch)
`404`	Resource not found
`409`	Conflict (example: payment routing locked)
`422`	Validation/business constraint failure (module dependent)
`429`	Rate limited (where limiter is enabled)
`500`	Internal server error

Code	Typical Cause
`authorization_required`	Missing token on `/api/public/v1/*`
`invalid_api_key`	Key missing/invalid/revoked/expired
`api_key_mode_mismatch`	Key mode does not match request mode
`invalid_oauth_token`	OAuth access token invalid/expired/revoked
`oauth_mode_mismatch`	OAuth token mode mismatch
`insufficient_scope`	Token/key lacks required scope
`unauthorized`	Merchant/admin endpoint called without valid auth
`invalid_body`	JSON decode failed
`not_found`	Resource ID not found
`internal_error`	Unhandled server failure

Capture x-request-id from response headers for incident tracing.
Confirm token type matches endpoint class (/api/v1/merchant vs /api/public/v1).
Confirm test/live mode alignment.
For OAuth, verify client_id, client_secret, redirect_uri, and scope set.