> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cashweb.cash/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Structured error model and endpoint-specific handling guidance.

## Error Shape

All errors use:

```json theme={null}
{
  "error": {
    "message": "...",
    "code": "...",
    "timestamp": "2026-02-12T12:00:00Z"
  }
}
```

## Common HTTP Statuses

* `400`: invalid request payload or query values.
* `401`: missing/invalid API key.
* `403`: feature unavailable in the current environment.
* `404`: resource not found in your partner scope.
* `409`: conflicting intent (idempotency mismatch or non-cancellable state).
* `429`: request throttled.
* `500`: internal error.
* `502`: upstream dependency issue.
* `503`: temporary capacity or availability issue.

## Handling Strategy

1. Retry only retry-safe statuses (`429`, `5xx`) with backoff.
2. Never mutate request body while reusing the same idempotency key.
3. For `409`, inspect conflict reason and resolve business intent.
4. For `403`, inspect whether the endpoint is environment-restricted before retrying.