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

​
Error format

API endpoint 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

This table also includes OAuth token endpoint errors. Those happen before you have a bearer token and are returned by /oauth/token.
CodeHTTP StatusDescription
invalid_client401Client ID or client secret is incorrect. Returned by the /oauth/token endpoint.
invalid_scope401The requested OAuth scope is not enabled on the application. Returned by the /oauth/token endpoint.
unauthorized401Bearer token is missing, expired, revoked, or invalid. OAuth access tokens expire after 2 hours. API token lifetimes depend on the expiration chosen when the token was created.
insufficient_scope403Token does not have the required scope for this endpoint. See Scopes.
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, never_subscribed, suppressed
sms_consentmust be one of: subscribed, unsubscribed, never_subscribed, single_opt_in
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. The response includes the id of the existing contact so you can update it directly. 
{
  "error": {
    "code": "conflict",
    "message": "A contact with this email already exists"
  },
  "id": "cus_x9y8z7w6v5u4t3s2"
}
To update the existing contact, use the Update a contact endpoint with the returned id.

​
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.