Requests and errors
Interpret application API responses without treating internal endpoints as a public contract.
Request validation
Requests can be rejected when their bodies, query parameters, path parameters or headers do not match the endpoint’s contract. A value accepted by the interface may still be rejected if the request does not match the endpoint’s schema.
Send only documented fields for an approved integration. Never rely on client-supplied account IDs or roles to grant access.
Common response classes
| Status | Meaning and next step |
|---|---|
| 400 | The request does not match the expected contract. Correct it before retrying. |
| 401 | Authentication is missing or invalid. Use the normal authentication flow. |
| 403 | The request is forbidden, including origin or permission failures. |
| 415 | The request body uses an unsupported content type. |
| 429 | A rate limit was reached. Respect retry guidance when provided. |
| 502 / 503 | An upstream dependency or the service is unavailable. Check status and avoid rapid retries. |
Retry deliberately
Do not retry a write merely because the client did not receive a success response. The action may already have completed.
Read-only requests and mutations have different retry risks. An idempotency key only protects a request when that specific endpoint explicitly supports it.
Keep diagnostics safe
Record the operation, status and time without logging credentials or private payloads. Redact personal information before sharing an error report.