Home / API / Errors and limits
Errors and limits
Four status codes carry almost all the failures, and telling them apart saves real debugging time — particularly 400 versus 403, which fail for opposite reasons.
Status codes
| Code | Means | What to do |
|---|---|---|
| 400 | Invalid input — the value never reached a gate. Malformed token, malformed file ID, batch too large, unknown folder value | Fix the shape of what you sent. Your credential may be perfectly valid |
| 403 | Gate failure — well-formed input, wrong capability | Fix the credential. The request shape was fine |
| 413 | Too large — payload over 5 MB, or an inline-content listing over the 3 MB ceiling | Split the payload, or list without inline content and fetch on demand |
| 507 | Lane full — 1000 pending files for that token | Fetch and mark-processed, then purge the processed folder |
The 400 that looks like a 403. Path and token components are validated by typed primitives before they reach storage, which is how path traversal is blocked at the type level. A prefixed token such as
tok_abc… — or a CLI fingerprint pasted straight in, sha256:a461… — fails the hex-only pattern and returns 400. It reads like a rejected credential; it is a rejected string. Use raw hex.Input patterns
| Input | Pattern |
|---|---|
append_token | ^[0-9a-f]{16,128}$ — hex only, no prefix |
file_id (append) | ^\d{13}_[0-9a-f]{24}\.enc$ — server-assigned, so you should be echoing one back |
vault_id | lowercase alphanumeric, 8–24 characters, no hyphens |
Limits
| Limit | Value | On breach |
|---|---|---|
| Payload per append write | 5 MB | 413 |
| Pending files per append token | 1000 | 507 |
| File IDs per batch (fetch / mark / purge) | 100 | 400 |
Operations per /vault/batch request | 100 | 400 |
| Inline content when listing | 3 MB cumulative | 413 |
| Append list page size | 50 default, 200 max | clamped silently |
read-base64 response | ~3.75 MB | use presigned reads above this |
The page-size clamp is silent: ask for 500 and you get 200 with no warning. Page with after_file_id rather than assuming your requested size was honoured.