Skip to main content

Error response format

All API errors follow the same structure:
  • err_code: machine-readable code for programmatic handling
  • errors: field-level detail, present on validation errors
  • message: human-readable summary

HTTP status codes

Retry strategy

For 429 and 5xx responses, retry with exponential backoff:
  • Wait 1s before the first retry
  • Double the wait on each subsequent attempt
  • Cap at 30s
  • Stop after 3 to 5 attempts and alert your team
For 4xx responses, retrying the same request will not help. Fix the request first.

What to show users vs what to log

Never expose err_code or raw error bodies to end users.

Error categories

Authentication failure

A missing header, an expired timestamp, an unknown key or a signature that doesn’t verify. These return HTTP 401 with an AUTH_* code. See authentication errors for every code and its fix.

Object not found or access denied

The resource doesn’t exist or doesn’t belong to your organization.

Missing required fields

A required field was omitted from the request body.

Blank field value

A field was included but left empty.

Format or length violation

A field value doesn’t match the expected format or exceeds length limits.

Business rule violation

The request is valid but conflicts with a business constraint.

Server error

Retry with backoff. If it persists, contact support@zapyd.com with the request ID and timestamp.