Errors - API Reference

Audienceful uses conventional HTTP status codes to indicate the success or failure of a request. Codes in the 2xx range indicate success, 4xx codes indicate a problem with the request (a missing field, a permission issue, a conflict, etc.), and 5xx codes indicate an error on Audienceful's side.

Every non-2xx v2 response uses a single, consistent error envelope:

JSON

{
  "error": {
    "type": "validation_error",
    "code": "invalid",
    "message": "The request body failed validation.",
    "errors": [
      { "field": "email", "message": "This field is required." }
    ]
  },
  "request_id": "9f2c1a7e5b8d4f31a0c6e2d9b7a4f108"
}

errorobject

Properties

typestring

A broad classification of the error. One of the error types below.

codestring

A machine-readable slug for the specific error, useful for programmatic handling.

messagestring

A human-readable summary of what went wrong.

errorsarray

Present only for validation_error. A list of the individual fields that failed validation, each with a field and a message.

request_idstring

The id of the request, matching the X-Request-Id response header. Include it when contacting support.

Error types

`type`	Typical status	Meaning
`validation_error`	`400`	The request body failed validation. See `errors[]` for per-field detail.
`invalid_request_error`	`400` / `405` / `415`	The request was malformed, used an unsupported method, or sent an unsupported media type.
`authentication_error`	`401`	The API key is missing or invalid.
`permission_error`	`403`	The API key is valid but lacks the scope required for this endpoint.
`not_found_error`	`404`	The requested resource does not exist in this workspace.
`conflict_error`	`409`	The request conflicts with existing state (e.g. a duplicate email, or an in-progress idempotent request).
`rate_limit_error`	`429`	You've exceeded a rate limit.
`api_error`	`500`	Something went wrong on Audienceful's side.

Validation errors (400) are the ones you'll see most often while integrating. Read the errors[] array to see exactly which fields were rejected and why.