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

# Errors

> Handle Sellfern public V1 API errors safely.

Sellfern public V1 errors use stable machine-readable codes so integrations and AI agents can recover safely.

| Status | Code                   | Meaning                                                         | Recommended handling                             |
| ------ | ---------------------- | --------------------------------------------------------------- | ------------------------------------------------ |
| `400`  | `validation_error`     | Request parameters or body are invalid.                         | Fix the request before retrying.                 |
| `401`  | `unauthorized`         | API key is missing, invalid, expired, or revoked.               | Stop and ask for a valid API key.                |
| `403`  | `missing_scope`        | API key lacks the required scope.                               | Request a key with the minimum additional scope. |
| `404`  | `not_found`            | Resource does not exist or is outside the API key organization. | Do not infer cross-organization ownership.       |
| `422`  | `idempotency_conflict` | Idempotency key was reused with a different request.            | Generate a new key for a new logical mutation.   |
| `429`  | `rate_limited`         | API key exceeded rate limits.                                   | Back off and retry later.                        |

## Error response shape

`error.details` is included when structured remediation data is available. `meta.request_id` is always safe to log and share with Sellfern support.

```json theme={null}
{
  "success": false,
  "error": {
    "code": "missing_scope",
    "message": "API key lacks the required scope for this endpoint.",
    "details": {
      "required_scope": "orders:read"
    }
  },
  "meta": {
    "request_id": "req_01HX..."
  }
}
```