Reference
Handle transport, plan, and provider failures separately.
Veritas errors combine middleware failures, route validation, upstream provider behavior, and asynchronous delivery states.
HTTP status guide
| Status | Meaning | Client action |
|---|---|---|
| 400 | Invalid request | Correct fields before retrying. |
| 401 | Missing API key | Attach x-api-key. |
| 402 | Plan or credit restriction | Upgrade, wait for reset, or change workspace. |
| 403 | Invalid key or missing permission | Check key activity and permissions. |
| 404 | Resource or provider receipt not found | Confirm identifiers before retrying. |
| 409 | Duplicate or conflicting state | Read the existing resource and reconcile. |
| 422 | Receipt found but verification/matching failed | Review amount, destination, or receipt data. |
| 429 | Rate limit exceeded | Wait for the limiter window and retry with backoff. |
| 500/502 | Server or upstream provider failure | Retry cautiously and preserve the response for support. |
Retry safety
GET resource reads are generally safe to retry. A verification retry can consume another rate-limit unit and another credit. POST create/confirm operations do not expose a universal idempotency key guarantee.
Provider failures
Some provider adapters return success: false with HTTP 200. Build a shared helper that rejects either a non-2xx status or an explicit failed body.