Errors

Errors use an HTTP status code and a JSON body.

{
  "status_code": 400,
  "error_code": "VALIDATION",
  "error_message": "Validation failed"
}

Branch on error_code, not on error_message: the text is not part of the contract. Common codes: VALIDATION, UNAUTHORIZED, FORBIDDEN, PERMISSION_DENIED, NOT_FOUND, CONFLICT, INSUFFICIENT_FUNDS, INVALID_2FA, RATE_LIMITED, API_ACCESS_DISABLED.

Status	Meaning
`400`	Invalid request or business rule error
`401`	Missing or invalid credentials
`403`	Authenticated user does not have permission
`404`	Resource not found
`409`	State conflict
`420`	Insufficient balance
`422`	Invalid 2FA code
`428`	2FA is required for this operation
`429`	Rate limit exceeded, or another operation on the same resource is in progress

Log the HTTP status, request id if present, endpoint, and sanitized request metadata. Do not log API keys, tokens, full card data, or customer secrets.

Start

MCP