Skip to main content

Error Handling

Design errors so API consumers can act on them quickly and operators can trace them in one hop.

  • Return a stable JSON shape: code, message, requestId, optional details.
  • Avoid leaking upstream stack traces or internal hostnames.
  • Use domain codes for business failures and HTTP codes for transport/policy failures.
  • Include requestId from Zerq logs in every non-2xx response.

Policy and gateway status map​

  • 401 -> unauthenticated caller.
  • 403 -> authenticated caller denied by profile/client policy.
  • 405 -> HTTP method not enabled on route.
  • 429 -> rate limit reached.

Workflow mapping example​

# Invalid auth token
curl -i "https://gateway.example.com/v1/payments" \
  -H "Authorization: Bearer invalid-token" \
  -H "X-Client-ID: checkout-ui" \
  -H "X-Profile-ID: prod-checkout"

Expected behavior: gateway returns 401 with a non-sensitive message and a traceable requestId.

Implementation tip​

At the workflow edge, map all upstream errors into a controlled set of responses so callers are not exposed to backend-specific error formats.