Errors

Every non-2xx response is RFC 9457 application/problem+json. The code member is a closed enum — these 9 values are the complete set, and new ones are only ever added in a new API version.

The type member is a link to the page for that code, so an error response always tells you where to read about itself.

The codes

Code	Status	Meaning
request_invalid	400	The request was malformed, or well-formed but semantically invalid.
unauthenticated	401	The request carried no bearer token, or the token was not recognised.
permission_denied	403	The caller authenticated successfully but is not allowed to perform this operation.
not_found	404	The resource does not exist, or is not visible to this credential.
conflict	409	The write could not be applied because the target was ambiguous.
rate_limited	429	The org’s request rate limit was exceeded.
internal_error	500	An unexpected error occurred inside the Ahoy API.
service_unavailable	503	A transient, retryable condition. Always carries Retry-After.
timeout	504	An upstream dependency did not respond in time.

Reading a problem response

{
  "type": "https://api-docs.ahoy.ai/rest/v1/errors/request_invalid",
  "title": "Unprocessable Content",
  "status": 422,
  "detail": "Unknown property 'emial' on object type 'ahoy_contact'.",
  "code": "request_invalid",
  "reason": "unknown_property",
  "field": "/filter/0/property",
  "request_id": "req_01J8Z2K9QW3X4Y5Z6A7B8C9D"
}

• code — the stable, closed classification. Branch on this.
• reason — an optional finer sub-code. Additive: treat an unrecognised value as the bare code.
• field — an RFC 6901 JSON Pointer to the offending part of your request.
• status — note that one code can appear at several statuses; title always matches the status actually sent.
• request_id — also returned as the Ahoy-Request-Id header on every response, success or failure.

When a single request has more than one problem, an errors array lists each {field, detail, reason} so you can fix them in one pass.