Skip to main content
When a request fails, the API returns a JSON error response with a consistent structure.

​
Error format

All errors follow this envelope: 
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid",
    "details": [
      {
        "field": "email",
        "message": "is required"
      }
    ]
  }
}
FieldDescription
codeA machine-readable error code (see table below)
messageA human-readable description of what went wrong
detailsAn optional array of field-level errors (present on validation failures)

​
Error codes

CodeHTTP StatusDescription
unauthorized401Bearer token is missing, expired, or invalid
insufficient_scope403Token does not have the required scope for this endpoint
not_found404The contact could not be found
conflict409A contact with this email or phone number already exists
validation_failed422One or more fields failed validation
rate_limited429Rate limit exceeded — see Rate Limits

​
Validation errors

A 422 validation_failed response includes a details array with specific field errors. For example, creating a contact without an email or phone number returns: 
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid",
    "details": [
      {
        "field": "base",
        "message": "email or phone_number is required"
      }
    ]
  }
}
Common validation messages:
FieldMessage
email / phone_numberemail or phone_number is required
phone_numbermust be a valid phone number in E.164 format
email_consentmust be one of: subscribed, unsubscribed, non_subscribed
sms_consentrequires a phone number from a supported country
custom_fieldsmust be a flat key-value object (no nested values)

​
Conflict errors

A 409 conflict is returned when you try to create a contact with an email or phone number that already belongs to an existing contact. 
{
  "error": {
    "code": "conflict",
    "message": "A contact with this email already exists"
  }
}
To update an existing contact, use the Update a contact endpoint instead.

​
Handling errors

  1. Check the HTTP status code first. The status code tells you the category of error.
  2. Parse the error body. Use the code field for programmatic handling and the message for logging.
  3. Only retry on 429. Rate limit errors are temporary — wait for Retry-After seconds, then retry. Other errors require fixing the request.