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

# HTTP status codes

> What each status code means in the Everabyte API and how to respond to it.

## Success

| Status | Meaning | Notes |
| - | - | - |
| `200` | Success | Most endpoints, including uploads |
| `206` | Partial content | Range download; includes `Content-Range` |

The API does not use `201` for uploads. Do not require it.

## Client errors

| Status | Meaning | Typical cause | Retry? |
| - | - | - | - |
| `400` | Bad request | Validation error, bad multipart, missing key state, invalid destination | No |
| `401` | Unauthorized | Missing, invalid, expired, or revoked key pair | No |
| `402` | Payment required | No active subscription, or insufficient storage for a write | No |
| `403` | Forbidden | Missing scope, wrong company type, surface denial, bucket scope, retention, legal hold, blocked device | No |
| `404` | Not found | Wrong ID, or resource not visible to the caller | No |
| `410` | Gone | Trash display window elapsed; item no longer restorable | No |
| `413` | Payload too large | Trial file cap, or plan file cap | No |
| `429` | Too many requests | Per-key rate limit | Yes, with backoff |

### 400 is broader than validation

A `400` can mean:

* the JSON body failed schema validation,
* an unknown field was sent to a strict schema,
* a multipart upload had no file part,
* the owning user has no active encryption keys,
* a destination folder does not belong to the destination bucket,
* a folder move omitted a required destination,
* a folder tree exceeded the depth limit.

Read the message for diagnosis, but branch on the status.

### 403 needs a second look

A `403` is not one condition. Check for a stable code first:

* `API_COMPANY_ONLY` — individual account
* `API_KEY_SURFACE_DENIED` — route family not allowed
* `API_BUCKET_SCOPE_DENIED` — bucket outside key scope
* `DEVICE_BLOCKED` — backup device blocked

If there is no code, assume a missing capability or a retention/legal-hold block.

## Server errors

| Status | Meaning | Retry? |
| - | - | - |
| `500` | Internal error | Verify write outcome before retrying |
| `502` | Upstream failure | Yes, with backoff |
| `503` | Service unavailable | Yes, with backoff |
| `504` | Upstream timeout | Verify write outcome before retrying |

In production, 5xx messages are replaced with a generic message. Do not expect schema or driver details.

## Status codes that are not part of the contract

The API does not document `201`, `202`, `204`, `304`, `405`, `406`, `409`, `415`, `422`, or `428` as stable outcomes for the published endpoints. If you observe one, treat it as an undocumented edge case and report it.

> [!NOTE]
>
> Version operations other than downloads, and the file-restore endpoint, can return HTTP `200` while the inner `data.status` is `400`, `404`, or `410`. See [Versions and restore](https://docs.everabyte.com/storage/versions-and-restore.md).

## Mapping to user experience

| Status | User-facing action |
| - | - |
| `400` | Fix the input; show a field-level error |
| `401` | Re-authenticate the integration; alert operators |
| `402` | Prompt billing or storage upgrade |
| `403` | Explain permission and offer an access request |
| `404` | Treat as missing; avoid leaking whether it exists elsewhere |
| `410` | Explain that recovery is no longer possible |
| `413` | Ask for a smaller file or a plan upgrade |
| `429` | Queue and retry; show a "busy" state |
| `5xx` | Show a generic failure and offer retry |

## Logging

Log:

* HTTP status,
* stable `code`,
* route template,
* timestamp,
* your request ID,
* latency.

Do not log:

* `X-Secret-Key`,
* full signed URLs,
* file contents,
* personal data from file names unless your policy allows it.


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