> ## 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.

# Stable error codes

> The machine-readable code values emitted by authentication, authorization, rate limiting, and MCP guards.

Only some failures carry a `code`. Codes are emitted by guards and middleware that construct the response directly. Controller errors generally return `{ status, message, error }` without a code.

## Storage API codes

| Code | HTTP | Meaning | What to do |
| - | - | - | - |
| `API_COMPANY_ONLY` | 403 | The key does not belong to a company account and is not device-bound | Use a company key |
| `API_KEY_SURFACE_DENIED` | 403 | The route is outside the API-key storage surface | Use a documented storage route |
| `API_BUCKET_SCOPE_DENIED` | 403 | The target bucket is outside the key's restriction | Use an allowed bucket or widen the key |
| `API_KEY_RATE_LIMITED` | 429 | Per-key request rate exceeded | Back off with jitter |
| `SUBSCRIPTION_REQUIRED` | 402 | No active subscription | Renew billing |
| `TRIAL_API_LIMIT_REACHED` | 403 | Trial call quota exhausted | Upgrade or wait for the quota window |
| `DEVICE_BLOCKED` | 403 | The backup device bound to the key was blocked | Contact the administrator |

## MCP codes

| Code | HTTP | Meaning |
| - | - | - |
| `MCP_SCOPE_REQUIRED` | 403 | The key does not include the `mcp` scope |
| `MCP_TRIAL_LOCKED` | 403 | MCP requires a paid subscription; trial accounts are refused |

## Codes that are not stable

Do not depend on:

* message text,
* validation field names,
* HTTP reason phrases,
* a `code` that is not in the tables above,
* the `error` field's contents.

If a response includes an unknown code, log it and treat the HTTP status as authoritative.

## The trial upload exception

A trial upload over 100 MB is rejected with `413`. The backend defines a trial-specific upload code internally, but the current controller path may return only the standard error envelope. Do not require a code to detect this case: use `413` plus your own pre-flight size check.

## Where codes are absent

These failures usually have no stable code:

* schema validation (`400`),
* missing scope on a normal controller route (`403`),
* file not found (`404`),
* retention or legal-hold block (`403` or `400`),
* restore window elapsed (`410`),
* decryption state failure (`400` or `5xx`),
* insufficient storage (`402`).

Handle them by status and by checking state before the request where possible.

## Example

```typescript theme={null}
function classify(status: number, code?: string) {
  if (code === "API_KEY_RATE_LIMITED") return "rate_limited";
  if (code === "TRIAL_API_LIMIT_REACHED") return "trial_exhausted";
  if (code === "SUBSCRIPTION_REQUIRED") return "billing_required";
  if (code === "API_BUCKET_SCOPE_DENIED") return "bucket_scope";
  if (code === "API_KEY_SURFACE_DENIED") return "surface_denied";
  if (code === "API_COMPANY_ONLY") return "company_required";
  if (code === "DEVICE_BLOCKED") return "device_blocked";
  if (status === 429) return "rate_limited";
  if (status === 402) return "billing_required";
  if (status === 403) return "permission_denied";
  if (status === 410) return "gone";
  return "unknown";
}
```


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