Developers
API authentication and errors
A robust integration separates correctable errors, refusals, and temporary outages.
#Overview
A robust integration separates correctable errors, refusals, and temporary outages.
#Common request contract
Use https://api.cdn.pizza, Accept: application/json, and Authorization: Bearer YOUR_API_TOKEN. Protected routes require an authenticated, verified user and sometimes an owner/admin/member role.
A 401 means missing or invalid token, 403 means permission or organization refusal, 404 means inaccessible resource, 422 means validation, 429 means rate limit, and 5xx means a temporary service failure. Do not retry every error.
#Retry policy
Correct the payload on 422.
Renew or revoke a token on 401 without logging it.
Respect permission on 403 and delay on 429.
Retry 5xx with bounded backoff only when the operation is safe to repeat.
#HTTP status and recovery
| Status | Description | Action |
|---|---|---|
| 400 | Unreadable request | Fix syntax or Content-Type. |
| 401 | Missing/invalid token | Renew the credential without logging it. |
| 403 | Insufficient permission | Check email, organization, and role. |
| 404 | Invisible resource | Recheck ID and organization. |
| 422 | Validation | Fix the reported fields. |
| 429 | Rate limited | Honor Retry-After. |
| 5xx | Temporary error | Retry with backoff only when safe. |