Errors

The API uses conventional HTTP status codes to indicate success or failure.

Status	Meaning
200 OK	Successful request
201 Created	Resource created (e.g. a webhook subscription)
202 Accepted	Accepted for asynchronous processing (e.g. inbound lead webhook)
204 No Content	Success with no body (e.g. a delete)
302 Found	Redirect to a presigned URL (e.g. attachment download)
400 Bad Request	Invalid or malformed request (validation/binding failure)
401 Unauthorized	Missing or invalid API key
404 Not Found	Resource not found
429 Too Many Requests	Rate limit exceeded (see Rate Limits)
500 Internal Server Error	Something went wrong on our side

Error response shape

Errors return a JSON body with a human-readable error message and optional details:

{
  "error": "human-readable error message",
  "details": "optional additional context"
}

There is no machine-readable error code field; branch on the HTTP status, not on the message string (messages may change and are localized).

The 429 rate-limit response is the one exception to this shape: it includes a retry_after field (seconds) alongside error.

Validation errors

Validation failures return 400 with a single generic message, not a per-field list. Internal field names are deliberately not echoed back, so you won't receive a structured map of field errors. Validate inputs against the API Reference schemas before sending.

Authentication errors

A missing, malformed, or invalid API key returns 401 Unauthorized with the standard error envelope. See Authentication.