Understand API errors and retries
Interpret authentication, authorization, validation, rate-limit and idempotency failures safely.
| Status | Meaning | Action |
|---|---|---|
| 400 / 422 | Malformed or invalid input | Correct the request; do not retry unchanged. |
| 401 | Credentials missing or invalid | Verify identifier, secret and Authorization encoding. |
| 403 | IP, scope or staff-role policy denied the action | Grant only the missing permission or correct the exact source IP. |
| 404 | Endpoint or requested record is unavailable | Verify private endpoint key and record ownership. |
| 409 | State or idempotency conflict | Read the response and reconcile state before retrying. |
| 429 | Rate limit reached | Back off with jitter and reduce request frequency. |
| 500 / 503 | Temporary server failure | Retry a bounded number of times only when the operation is idempotent. |
Record a safe diagnostic
Store timestamp, action, HTTP status, sanitized error code and request reference. Never log the Authorization header, API secret, activation key, payment details or complete customer payload.