# Errors and status codes

Log the status, request identifier, safe response details, and retryability; correct invalid requests, reauthenticate on authorization errors, and back off on transient limits.

## Where this lives

Use a trusted local or server-side API client.

The Foxora API provides OpenAI-compatible chat completions plus account, usage, and public model-discovery endpoints. Authenticated routes currently accept a signed-in Foxora account access token.

> **Safety:** Treat the complete account access token as a secret. Do not paste it into prompts, commit it to a repository, expose it in client-side bundles, or include it in logs, screenshots, and support messages.

## Steps

1. Use a trusted local or server-side API client.
2. Log the status, request identifier, safe response details, and retryability.
3. Correct invalid requests, reauthenticate on authorization errors, and back off on transient limits.
4. **Confirm the result.** Inspect HTTP status, response headers, request identifiers, usage fields, and the parsed response; cross-check account or usage endpoints after a small request.

## Choose the right path

- Use `/v1/chat/completions` for OpenAI-compatible generation.
- Use `/v1/me` and `/v1/me/usage` for account and usage state.
- Use `/v1/models` to discover model identifiers instead of hardcoding assumptions.

## Error handling guide

| Status | Meaning | Client action |
| --- | --- | --- |
| 400 | Invalid request | Fix the payload; do not retry it unchanged. |
| 401 | Missing, expired, or invalid authentication | Refresh the account session and replace the access token. |
| 403 | Account or feature not permitted | Verify account, plan, and key scope. |
| 404 | Endpoint or resource not found | Check the API path and resource identifier. |
| 429 | Rate or usage limit reached | Respect retry guidance and reduce request rate. |
| 5xx | Temporary service failure | Retry only idempotent work with bounded backoff and jitter. |


## Confirm it worked

- Inspect HTTP status, response headers, request identifiers, usage fields, and the parsed response; cross-check account or usage endpoints after a small request.
- The screen, command, file, run, or destination named in this guide reflects the expected state.