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

# Troubleshooting

> Diagnose common integration failures using symptoms, status codes, and verified causes.

## First checks

Before deep debugging, confirm:

1. The base URL ends with `/api`.
2. Both `X-Public-Key` and `X-Secret-Key` are present.
3. The key is active and not expired.
4. The key belongs to a company account.
5. The key includes both the bucket scope and the resource scope for the operation.
6. The target bucket is within the key's restriction.
7. The company has active billing, or a valid trial.
8. The owning user has active encryption keys for uploads.

## Symptom: every request returns 401

| Cause | Check |
| - | - |
| Header names misspelled | Must be exactly `X-Public-Key` and `X-Secret-Key` |
| Secret has whitespace or a newline | Trim environment values |
| Key was rotated | Update the deployed secret |
| Key was revoked | Create a replacement |
| Key expired | Check expiry in the dashboard |
| Copy/paste lost characters | Re-copy from the secret manager |

A 401 does not tell you which of these is true. Do not retry aggressively; fix the credential.

## Symptom: 403 API\_COMPANY\_ONLY

The key belongs to an individual account. The developer REST API is company-only.

* Switch to a company workspace.
* Create a company key.
* If you are building a backup agent, use the device-bound key flow instead.

## Symptom: 403 without a code

Usually a missing capability. Common cases:

| Operation | Often missing |
| - | - |
| Upload | `buckets:write` or `files:write` |
| Delete file | `buckets:write` or `files:delete` |
| Delete folder | `buckets:write` or `folders:delete` |
| List folder content | `buckets:read` or `folders:read` |
| Download file | `buckets:read` or `files:read` |

It can also be a retention or legal-hold block. Check `isRetention` before retrying.

## Symptom: 403 API\_BUCKET\_SCOPE\_DENIED

The key is restricted to other buckets.

* Compare the `bucketId` in the request with the bucket restriction shown in the dashboard.
* Use an allowed bucket.
* If the integration genuinely needs more buckets, update the key in the dashboard.

Do not create a second key to work around this without reviewing why the restriction exists.

## Symptom: 403 API\_KEY\_SURFACE\_DENIED

The route is not part of the storage surface. Sharing, audit, billing, tags, and administration routes are not available to API keys.

Use a documented endpoint or perform the action in the dashboard.

## Symptom: upload fails with 400

| Message theme | Cause |
| - | - |
| Encryption keys | No active HPKE keys for the owning user |
| No files | Multipart body had no file part |
| Multipart error | Malformed body or wrong content type |
| Folder not found | Folder ID invalid or outside the bucket |
| Cross-bucket | Folder and bucket do not match |

Fix the state; retrying the same request will not help.

## Symptom: upload fails with 413

* Trial accounts are capped at 100 MB per file.
* Paid accounts are capped by plan.

Reduce the file size or upgrade. Pre-check size in your client before sending.

## Symptom: upload fails with 402

Insufficient storage or inactive billing. Check stored size with `GET /buckets/size/{bucketId}`; the dashboard shows plan capacity.

## Symptom: upload succeeds but the file is not where expected

* Confirm which folder segment you used.
* Check `effectiveFolderId` in the response.
* A multi-file request returns only the first result; list the folder to find the rest.
* A same-name upload may have created a version of an existing file rather than a new file. Check `isUpdate`.

## Symptom: download is corrupt or truncated

| Cause | Fix |
| - | - |
| Client decompressed a binary body | Disable automatic decompression |
| Proxy rewrote `Content-Length` | Fix proxy buffering |
| Range response treated as full content | Preserve `206` and `Content-Range` |
| Total request timeout cut the stream | Use socket inactivity timeouts |
| File changed during read | Pin a `versionId` and download that version |

If corruption persists, compare the SHA-256 of the downloaded bytes with your source.

## Symptom: version endpoints return 200 but nothing happened

Version and restore endpoints nest a service result. Check `data.status`:

* `404` — file or version missing,
* `400` — already current, not in trash, or invalid key envelope,
* `410` — restore window elapsed.

## Symptom: 410 on restore

The trash display window has elapsed. The item is no longer restorable. The physical purge schedule is separate, but restore is no longer available.

## Symptom: 429

Reduce concurrency, back off, and split workloads across keys. See [Rate limits](https://docs.everabyte.com/authentication/rate-limits.md).

## Symptom: CORS error in the browser

API key headers are not CORS-allowed. The preflight fails before the request reaches the API. Move the call to your backend.

## Symptom: 5xx

The response body is sanitized in production. Collect:

* timestamp with timezone,
* route template,
* HTTP status,
* response `code` if any,
* your request ID,
* whether the operation was a read or a write.

For writes, verify state before retrying. Contact support if it persists.

## What to send support

Include:

```text theme={null}
Company ID:
Key prefix (first 12 characters only):
Route and method:
Timestamp with timezone:
HTTP status and code:
Request ID:
What you expected vs observed:
```

Never send the secret key, file contents, or full signed URLs.


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