Errors

Errors follow RFC 7807 problem details (application/problem+json). The status mirrors the HTTP code.

The error object

Field	Type	Description
type	string (uri)	A URI reference that identifies the problem type
title	string	A short, human-readable summary of the problem type
status	integer	The HTTP status code generated by the origin server
detail	string	A human-readable explanation specific to this occurrence of the problem
instance	string | null	A URI reference that identifies the specific occurrence of the problem
errors	object	Optional validation error details

{
  "type": "about:blank",
  "title": "Invalid request signature",
  "status": 401,
  "detail": "Invalid request signature",
  "instance": null,
  "errors": {}
}

For 422 errors, errors carries field-level validation messages:

{
  "type": "about:blank",
  "title": "Invalid request parameters",
  "status": 422,
  "detail": "Validation failed: Amount must be greater than 0",
  "instance": null,
  "errors": {
    "amount": ["must be greater than 0"]
  }
}

A signature 401 carries extra detail to help you debug it — see Sign requests. The two idempotency errors use a different body — see Idempotency.

Which errors to retry, and how: Handle errors and retries.

Status codes

Status	Meaning
400	Bad request — malformed JSON, an event batch that failed validation, or an empty Idempotency-Key
401	Invalid zay-api-key or signature
403	Access forbidden
404	Resource not found
413	Event batch too large
422	Validation error in request body
429	Rate limit exceeded — see Rate limits — or a request with the same Idempotency-Key is still in progress — see Idempotency
503	Service unavailable

Each endpoint lists the errors it returns, and what causes them.