# Errors and troubleshooting

Interpret the shared API error envelope and handle retries without duplicating writes.

## Response shape

Successful calls return a data field. Failed calls return error.code and error.message with an HTTP status. Messages are sanitized for the caller; do not depend on internal provider responses.

## Common statuses

- 400 — invalid JSON, unknown operation or input validation failure.
- 401 — authentication is missing, invalid, expired or no longer usable.
- 403 — missing scope, unsupported operation, account entitlement or origin requirement.
- 404 — resource not found or not visible to this principal.
- 409 — conflicting state, stale version or a review gate that needs action.
- 429 — rate limit or daily AI budget reached. Respect Retry-After when present.
- 503 — provider, database or model configuration is unavailable. Check the deployment prerequisites and retry only after the issue is resolved.

## Safe retries

Do not retry unchanged 400, 401, 402 or 403 errors. Before repeating a write after a timeout, check whether the operation supports an idempotency key or expected version. Refresh a stale draft before retrying publish.