Skip to main content

​
Error response format

All errors return this structure: 
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "payment_amount must be a positive integer (cents)",
    "field": "payment_amount",
    "request_id": "4e9024e3-125d-4d08-a392-4fa34f6bda44"
  }
}
PropertyAlways presentDescription
codeYesMachine-readable error code
messageYesHuman-readable description
fieldNoDot-notation path to the problematic field (e.g., address.state). Only present when a specific field caused the error.
request_idYesUnique UUID for this request. Include in support tickets.

​
Error codes

CodeHTTP StatusDescription
VALIDATION_ERROR400Invalid request body or query parameters
AUTHENTICATION_ERROR401Missing, malformed, or invalid API key
AUTHORIZATION_ERROR403Valid key but not permitted (e.g., suspended account, disallowed payment type)
NOT_FOUND404Resource not found or belongs to a different partner
CONFLICT409Duplicate resource (same email, external_id, or billing period)
RATE_LIMITED429Too many requests
INTERNAL_ERROR500Unexpected server error

​
Example error responses

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Must be YYYY-MM-DD",
    "field": "date_of_birth",
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

{
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Missing x-api-key header",
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Consumer not found",
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

{
  "error": {
    "code": "CONFLICT",
    "message": "A consumer with this email or external_id already exists for this partner",
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

​
Tips

  • Always check for the error key in the response before processing data.
  • Use field for field-level error highlighting in your UI.
  • Include request_id when contacting support.