Errors & limits

Error codes, quota behaviour, rate limits and how to handle them in your UI and backend.

Error format

HTTP/1.1 409 Conflict
X-Request-Id: req_…
{ "error": { "code": "files_pending", "message": "Some files are still being uploaded or checked.", "requestId": "req_…" } }

Common codes

Code	HTTP	Meaning / what to do
`unauthorized`	401	Missing or invalid credential.
`credential_expired`	401	The session capability expired. Open the picker again.
`insufficient_scope`	403	The credential doesn’t allow this operation (for example a phone capability calling a manage route).
`public_key_not_allowed`	403	A `pk_` key was used where a secret key is required.
`origin_not_allowed`	403	The page origin isn’t in the project allowlist.
`not_found`	404	Doesn’t exist or belongs to another tenant/project.
`file_too_large`, `type_not_allowed`, `too_many_files`, `empty_file`	400	Rejected before upload by session policy.
`upload_quota_exhausted`, `storage_quota_exhausted`	402	Your plan limit is reached. Visitors see “Uploads are temporarily unavailable”; you see details in the dashboard.
`initiation_limit`, `rate_limited`	429	Abuse limits. Back off and retry later.
`session_expired`, `pairing_expired`	410	Start a new session / refresh the QR.
`pairing_used`, `phone_already_paired`	409	The QR was already redeemed.
`idempotency_key_reused`	409	Same key, different request body.
`files_pending`, `no_ready_files`	409	Finish was called too early.
`billing_not_configured`	503	Stripe isn’t configured on this deployment; no payment was taken.

File rejection codes

Delivered on the file object and in file.rejected: type_mismatch, malware_detected, file_too_large, empty_file, missing_object, and verification_unavailable (status failed: verification could not run after retries — never marked clean).

Limits are distinct

Monthly accepted files (per account, across all projects)
Files per picker session (plan ceiling, lowered by project and request)
Bytes per file
Live stored bytes
Delivered bytes (a budget with reconciliation, not a real-time cap)

Dashboard notices appear at 80% and 100% of monthly uploads and storage.

Something unclear or wrong? Email [email protected].