# 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.