Error Handling

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"
  }
}

Property	Always present	Description
`code`	Yes	Machine-readable error code
`message`	Yes	Human-readable description
`field`	No	Dot-notation path to the problematic field (e.g., `address.state`). Only present when a specific field caused the error.
`request_id`	Yes	Unique UUID for this request. Include in support tickets.

Error codes

Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Invalid request body or query parameters
`AUTHENTICATION_ERROR`	401	Missing, malformed, or invalid API key
`AUTHORIZATION_ERROR`	403	Valid key but not permitted (e.g., suspended account, disallowed payment type)
`NOT_FOUND`	404	Resource not found or belongs to a different partner
`CONFLICT`	409	Duplicate resource (same email, external_id, or billing period)
`RATE_LIMITED`	429	Too many requests
`INTERNAL_ERROR`	500	Unexpected server error

Example error responses

400 — Validation Error

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

401 — Authentication Error

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

404 — Not Found

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

409 — Conflict

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

Getting Started

Core Concepts

Reference

Migration

Error response format

Error codes

Example error responses

Tips

​Error response format

​Error codes

​Example error responses

​Tips

Error response format

Error codes

Example error responses

Tips