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

# Error Handling

Errors should be predictable for API clients while keeping internal details private.

## Client handling

Inspect the actual response shape and status mapping in the deployed release. Common HTTP meanings include:

| Status | General meaning | Client action |
| - | - | - |
| 400 | Invalid request | Correct payload and validation errors |
| 401 | Missing/invalid authentication | Re-authenticate |
| 403 | Authenticated but not permitted | Check role, permission, ownership, and tenant |
| 404 | Route/resource not found | Check URL, identifier, edition, and visibility |
| 409 | State/uniqueness conflict | Refresh state; do not blindly retry |
| 413 | Request too large | Reduce payload or adjust approved limits |
| 415 | Unsupported media type | Use the expected content type |
| 429 | Rate limit | Back off according to policy |
| 5xx | Server/provider failure | Retry only when operation is safe and idempotent |

## Server-side rules

Return safe, actionable messages and stable error identifiers where implemented. Do not expose stack traces, SQL, secrets, filesystem paths, or provider credentials. Log diagnostic details with a request/correlation ID and redact personal/payment data.

## Retry guidance

GET requests are generally safer to retry than writes. For payment, order, and webhook operations, use idempotency controls before retrying.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.