Every error code, the rate limits, the response headers and what to do when something goes wrong.
Things go wrong sometimes. A key gets revoked, a link expires, a photographer submits a correction at the worst possible moment. The API tells you what happened in a predictable way, so your integration can deal with it calmly.
Spreadu-Mode, x-request-id and
Cache-Control: no-store.{ amountMinor: string, currency }, with an ISO 4217
currency code.Retrying safely. Simulator writes accept an optional Idempotency-Key; use
it when you retry the same command. Creating a webhook uses its URL as the
natural key instead. Repeating a receipt, or the same confirmation while the
album is locked, answers changed: false.
| Allowance | Limit | Shared by |
|---|---|---|
| Lab | 600 requests per minute | All of the lab's keys. |
| IP address | 600 requests per minute | Everyone calling from that address. IPv6 addresses in the same /64 share one. |
| Simulator | 60 requests per minute | Requests under /sandbox/, on top of the other two. |
When an allowance runs out you get 429 RATE_LIMITED with a Retry-After
header. Wait that many seconds before trying again.
| Header | When | Meaning |
|---|---|---|
X-RateLimit-Limit | Every response except 413 | The allowance of the tightest bucket that counted this request: IP, lab or simulator. |
X-RateLimit-Remaining | Same | Requests left in that same bucket. Equal to the limit, with no reset, while Spreadu can't count. |
X-RateLimit-Reset | Same, while counting works | Unix time in seconds when that bucket resets. |
Retry-After | 429 | Seconds to wait before retrying. |
Idempotency-Replayed | A replayed simulator command | true when the response is the stored result of an earlier command with the same Idempotency-Key. |
Spreadu-Mode | Every response | test only when a test key authenticated the request; live for everything else, including a refused key. |
x-request-id | Every response | Include it when you ask us about a request. |
The three X-RateLimit-* values always describe the same bucket, so you can
pace your requests from them directly.
Every error is JSON in one shape:
{ "defined": true, "code": "REVISION_NOT_DOWNLOADABLE", "status": 409, "message": "This revision is no longer downloadable", "data": { "downloadableRevision": 3 } }Branch on code. Not on message, whose wording can change, and not on
defined. data is part of the contract only for codes that declare it. Other
errors may include an informal hint there, such as the name of a refused field.
Don't branch on it.
For the curious: defined is true for an error the operation declares,
including the 401 INVALID_API_KEY and 403 API_ACCESS_DISABLED refusals any
request can get. It's false for NOT_FOUND, PAYLOAD_TOO_LARGE,
RATE_LIMITED, INTERNAL_SERVER_ERROR and any other error the operation
doesn't declare. A 400 BAD_REQUEST can carry either value: a body that can't
be decoded, such as invalid JSON, is refused before the operation runs, with
false. The API reference
lists the codes each operation can return.
| Code | HTTP | What it means | What to do |
|---|---|---|---|
BAD_REQUEST | 400 | A field, query value, cursor, types value or Idempotency-Key is invalid, or an unknown field was sent. | Fix the request. If a cursor was altered, restart the export list without cursor or the feed without after. |
INVALID_API_KEY | 401 | The key is missing, malformed, unknown or revoked. | Check the header. If the key was revoked, ask a lab owner or manager for a new one. |
API_ACCESS_DISABLED | 403 | API access is off for your lab or globally. For a test key: Test mode is paused or your lab isn't active. | Stop and ask your Spreadu contact. Retrying won't help. |
MODULE_NOT_ENABLED | 403 | The operation's module isn't enabled. data.module names it. | Ask Spreadu to enable the module. |
INSUFFICIENT_SCOPE | 403 | The key lacks data.requiredScope. | Use a key with that scope. |
TEST_MODE_REQUIRED | 403 | A live key called a simulator operation. | Use a test key. |
NOT_FOUND | 404 | No operation exists at that path and method. | Check the path and method against the reference. |
EXPORT_NOT_FOUND | 404 | No export with that reference belongs to your lab. | Check the reference. Another lab's export looks the same as a missing one. |
FILE_NOT_FOUND | 404 | A fileIds entry isn't part of the requested revision. | Read the export again and request current file IDs. |
REVISION_NOT_FOUND | 404 | The receipt names a revision that was never published. | Record receipts only for revisions you downloaded. |
WEBHOOK_NOT_FOUND | 404 | No endpoint with that ID was created by this key. | See webhook management errors. |
REVISION_NOT_DOWNLOADABLE | 409 | The revision isn't the one this request accepts right now. | Retry with data.downloadableRevision. When it's null, wait for an event. |
IDEMPOTENCY_CONFLICT | 409 | A simulator Idempotency-Key was already used for another operation or body. | Give each new command a new key. |
SANDBOX_BUSY | 409 | Another test-mode write for the same lab is in progress. | Retry the same request shortly, with the same idempotency key where it applies. See the simulator. |
SANDBOX_EXPORT_LIMIT | 409 | The test environment already holds 50 test exports that are ready or still being prepared. | Reset the sandbox. |
SANDBOX_EXPORT_LOCKED | 409 | A simulated photographer change hit your lab lock. | Unlock the test export first. |
SANDBOX_STATE_CONFLICT | 409 | The test export isn't in a state that allows this simulator command. | Read the export, then choose the next command. |
ENDPOINT_LIMIT_REACHED | 409 | The lab already has five webhook endpoints. | See webhook management errors. |
WEBHOOK_URL_EXISTS | 409 | Another endpoint already uses that URL. | See webhook management errors. |
WEBHOOK_DISABLED | 409 | A test was sent to a disabled endpoint. | Enable the endpoint first. |
CURSOR_EXPIRED | 410 | The event cursor is older than the 30-day window or ahead of the stream. | Catch up with GET /exports, then restart the feed without after. See Recover from 410. |
PAYLOAD_TOO_LARGE | 413 | The body is over 32 KB. | Send fewer fileIds per request. |
RATE_LIMITED | 429 | An IP, lab or simulator allowance is used up. | Wait Retry-After seconds. |
INTERNAL_SERVER_ERROR | 500 | Something went wrong on our side. | Retry with backoff, and send us the x-request-id if it keeps happening. |
SERVICE_UNAVAILABLE | 503 | Webhook secret storage is temporarily unavailable. Nothing changed. | Retry later. |
data.downloadableRevision on REVISION_NOT_DOWNLOADABLE is the revision your
request would succeed with right now, so you can retry without reading the
export first. For downloads it equals the export's current
downloadableRevision. For confirmation it's also null while the album isn't
finalized, for example while the photographer prepares a new revision.
NOT_FOUND, PAYLOAD_TOO_LARGE, RATE_LIMITED and INTERNAL_SERVER_ERROR come
from the platform around the operations.
404 NOT_FOUND only with a valid key; without one it answers
401 INVALID_API_KEY.413 is sent before the key is checked.429 body keeps two older fields next to the shared shape, so clients
written for it keep working:{ "defined": false, "code": "RATE_LIMITED", "status": 429, "error": "RATE_LIMITED", "message": "Too many requests, please try again later", "retryAfter": 42 }Start with the request log in API settings. For every call it shows the
method, path, status, error code, duration and x-request-id. It keeps the
last 50 authenticated calls per key, in both modes, and stores metadata only. A burst refused by the lab or simulator allowance shows up as one
429 RATE_LIMITED entry per key and allowance for the rest of that minute, so
a burst refused by both can show two.
| Symptom or code | Try this |
|---|---|
Test mode is unavailable, or API_ACCESS_DISABLED | Check that your lab is active and that Spreadu has Test mode switched on. While Test mode is paused, test keys are refused but stay listed and can be revoked. Live and test access are separate. |
INVALID_API_KEY | Send Authorization: Bearer <complete-key> and check that the key wasn't revoked. Never paste the webhook secret here. |
TEST_MODE_REQUIRED | Use a spreadu_lab_test_ key for simulator endpoints. |
INSUFFICIENT_SCOPE or MODULE_NOT_ENABLED | Use a test key with sandbox:manage for the simulator, and the usual export and webhook scopes for those operations. |
EXPORT_NOT_FOUND | Check the reference and the mode. Test keys can't see live exports or another lab's exports. |
REVISION_NOT_DOWNLOADABLE | Wait for export.available, or use data.downloadableRevision when it isn't null. A withdrawn or expired revision isn't worth retrying. |
IDEMPOTENCY_CONFLICT | Reuse a key only for the original operation and body. Give a different command a new key. |
SANDBOX_BUSY | Another test-mode write is running. Retry the same command shortly. |
SANDBOX_EXPORT_LOCKED | Call DELETE /exports/{reference}/lock with an exports:confirm key. |
SANDBOX_STATE_CONFLICT | Read the current export before choosing the next action. |
SANDBOX_EXPORT_LIMIT | Reset the sandbox. |
No webhook, or DNS_REJECTED, CONNECT_FAILED, HTTP_STATUS | Keep the HTTPS tunnel running, check its current URL and your receiver's route, return 2xx after recording the event, and inspect or resend the delivery. Local and private addresses aren't allowed. |
| Signature failure | Verify the exact raw body with the right endpoint secret and a synchronised clock. Use Resend for a fresh attempt instead of replaying an old capture. |
CURSOR_EXPIRED after a long pause or a reset | Catch up with GET /exports and restart the feed without after. |
For a retryable network failure or a 5xx, back off and retry the same simulator command
with its original idempotency key. Check the request log before creating
replacement work.
Still stuck? Write to [email protected] with the
x-request-id. It lets us find your exact request.
Allow analytics to help us improve these docs? We measure page visits and outgoing links. No session recordings. Privacy policy