# Errors and status codes

Handle Foxora API failures by HTTP status, structured error code, and `x-request-id`, while keeping credentials and prompt content out of logs.

| Status | Meaning | Client action |
| --- | --- | --- |
| `400` | Invalid request | Fix the payload; do not retry unchanged. |
| `401` | Authentication failed | Refresh or replace the account token. |
| `403` | Feature or plan denied | Verify entitlement and requested model. |
| `404` | Route or resource missing | Check the `/v1` path and identifier. |
| `429` | Request ceiling reached | Wait for reset guidance and reduce concurrency. |
| `5xx` | Service failure | Retry safe work with bounded backoff and jitter. |

Unknown routes return `NOT_FOUND`; validation failures return `VALIDATION_ERROR`; unexpected failures return `INTERNAL_ERROR`. Upstream-specific messages may vary, so do not build control flow from prose.

**Expected result:** the client either corrects a permanent request error or performs a bounded retry while retaining the request identifier for support.