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

# Errors

> HTTP status codes, error shapes, and how to handle them.

Denialbase uses conventional HTTP status codes and a consistent error shape.

## Status codes

| Code                        | Meaning                                         | Retry?                    |
| --------------------------- | ----------------------------------------------- | ------------------------- |
| `200` OK                    | Request succeeded                               | —                         |
| `201` Created               | Resource created                                | —                         |
| `204` No Content            | Success, empty body                             | —                         |
| `301` / `302`               | Redirect                                        | Follow                    |
| `400` Bad Request           | Malformed JSON or invalid request shape         | No — fix the request      |
| `401` Unauthorized          | Missing or invalid authentication               | Re-authenticate           |
| `402` Two-Factor Required   | Complete the 2FA step                           | Complete 2FA              |
| `403` Forbidden             | Authenticated but not authorized                | No — you lack permission  |
| `404` Not Found             | Resource doesn't exist or is not visible to you | No                        |
| `409` Conflict              | State conflict (e.g. duplicate, stale update)   | Refetch, reconcile        |
| `422` Unprocessable Entity  | Validation failed                               | No — fix the payload      |
| `429` Too Many Requests     | Rate limit hit                                  | Yes — honor `Retry-After` |
| `500` Internal Server Error | Unexpected server error                         | Yes — with backoff        |
| `502` / `503` / `504`       | Transient infrastructure issue                  | Yes — with backoff        |

## Error response shape

```json theme={null}
{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields failed validation.",
    "details": [
      { "field": "email", "message": "must be a valid email" },
      { "field": "denial_type", "message": "must be one of medical_necessity, prior_authorization, …" }
    ],
    "request_id": "req_01J9K7V5M3P8A2B1C6D4E7F9"
  }
}
```

* `code` — stable machine-readable identifier. Safe to switch on.
* `message` — human-readable, may change wording.
* `details` — optional, present for validation-type errors.
* `request_id` — include when reporting issues to support.

## Common error codes

| `code`                | HTTP | Meaning                                                 |
| --------------------- | ---- | ------------------------------------------------------- |
| `not_authenticated`   | 401  | No valid session.                                       |
| `two_factor_required` | 402  | Sign-in needs 2FA completion.                           |
| `not_authorized`      | 403  | Pundit policy denied the action.                        |
| `not_found`           | 404  | Resource doesn't exist or isn't visible.                |
| `validation_failed`   | 422  | One or more fields invalid. `details` populated.        |
| `rate_limited`        | 429  | Too many requests. `Retry-After` header set.            |
| `conflict`            | 409  | Concurrent modification; refetch and retry.             |
| `file_too_large`      | 413  | Upload exceeds 50 MB.                                   |
| `virus_detected`      | 422  | Uploaded file failed virus scan. Will not be processed. |
| `internal_error`      | 500  | Our bug. Please report with the `request_id`.           |

## Retry strategy

<CardGroup cols={2}>
  <Card title="Idempotent reads" icon="rotate">
    `GET` requests can be retried freely. Use exponential backoff (starting at 500ms, capped at 30s) on transient errors.
  </Card>

  <Card title="Non-idempotent writes" icon="shield-halved">
    `POST` / `PUT` / `PATCH` / `DELETE` — include an `Idempotency-Key` header (UUID). Denialbase will dedupe retries of the same key within a 24-hour window.
  </Card>
</CardGroup>

### Idempotency example

```bash theme={null}
curl -X POST https://api.denialbase.com/api/v1/documents \
  -H "Cookie: $SESSION_COOKIE" \
  -H "Idempotency-Key: 0f7c9e42-1a23-4b5c-9d0e-1234567890ab" \
  -F "file=@denial.pdf"
```

If the request times out and you retry with the same key, Denialbase returns the result of the original attempt — not a duplicate upload.

## Reporting errors

When reporting an error to support, include:

* The `request_id` from the error response (most useful).
* The endpoint and method.
* The approximate time (ISO 8601 with timezone).
* What you expected to happen.

Email: [support@denialbase.com](mailto:support@denialbase.com).