Errors

Error response format

All API errors follow a consistent structure:

1
{
2
  "error": {
3
    "type": "validation_error",
4
    "message": "The request data is invalid.",
5
    "errors": [
6
      {
7
        "field": "email",
8
        "message": "The email field is required."
9
      }
10
    ]
11
  }
12
}

The error.type field is a machine-readable string you can use in your code. The error.message field is a human-readable description. The error.errors array is only present for validation errors and contains field-level details.

Error types

Validation errors

When a request fails validation, the response includes a 422 status and field-level error details:

1
{
2
  "error": {
3
    "type": "validation_error",
4
    "message": "The request data is invalid.",
5
    "errors": [
6
      {
7
        "field": "customer_id",
8
        "message": "The customer id field is required."
9
      },
10
      {
11
        "field": "plan_id",
12
        "message": "The plan id field is required."
13
      }
14
    ]
15
  }
16
}

Each entry in the errors array includes the field name and a descriptive message.

Handling errors

Best practices for error handling in your integration:

• Check error.type rather than parsing the message string. Types are stable; messages may change.
• Retry on 429 after the duration specified in the Retry-After response header.
• Retry on 500 with exponential backoff. If errors persist, contact support.
• Do not retry 401, 403, 404, or 422 — these indicate issues with your request that require code changes.
• Log the full error response for debugging. Include the request method, path, and any request body (redacting sensitive fields).