Errors and limits
Every error says what went wrong and what to do next.
An error
{
"error": {
"code": "insufficient_tokens",
"message": "Not enough tokens for this screening — nothing was sent.",
"hint": "Top up tokens in Carousel, then retry the same request …"
}
}code is stable — branch on it. message says what happened; hint is the next thing to do.
Codes
- 400
invalid_request— Fix the field the message names. Unknown fields are refused too, and so is a malformedchecks: not a list, empty, more than 12, with a duplicate, or with an id that isn’t lowercase letters and_. A key limited to some workspaces that sends with onlyregiongets it too: “This key is limited to some workspaces — name a workspace or building.” - 400
invalid_email— Send the applicant’s email address inapplicant.email— phone numbers aren’t accepted. - 401
unauthorized— SendAuthorization: Bearer <key>with a key that hasn’t been revoked — live (cp_live_…) or test (cp_test_…). A connected assistant whose connection expired or was revoked reconnects instead. - 402
insufficient_tokens— Top up tokens in Carousel, then retry the same request (the same Idempotency-Key works) — or send with"payer": "renter". - 403
results_not_allowed— This key wasn’t made to read applicant results — create one with Read applicant results ticked. As a developer on someone else’s account, a live one needs the owner to switch on Can see applicant data for you. - 403
view_links_not_allowed— This key wasn’t made to show reports in your app — create one with Show reports in my app ticked. As a developer on someone else’s account, a live one needs the owner to switch on Can see applicant data for you. - 403
not_allowed— The key reaches that workspace, but your role there can’t do this: View only can’t send screenings or add buildings. Ask the workspace’s owner to make you Can screen or Can spend … tokens, or use a workspace where you can:GET /workspacessays each one’sroleandcanSend. Or a key limited to some workspaces tried to make a workspace (“This key is limited to some workspaces, so it can’t make new ones.”): make the workspace in Carousel, then a key that names it. - 404
not_found— Use an id this key can reach:GET /workspaces,/buildingsor/screeningslist them. One outside the key’s reach answers exactly like one that doesn’t exist. - 409
idempotency_conflict— That Idempotency-Key was used with a different body, even one only formatted differently — use a new key for a new send. - 409
request_in_progress— The first request with that key is still running — repeat it in a few seconds. - 409
results_changed— The bank data changed between transaction pages — start again withafter=0. - 409
region_mismatch— Theregionyou sent isn’t the workspace’s or building’s. Leave it out, or send theirs. - 413
document_too_large— Download the file in ranges:Range: bytes=0-4194303, then the next 4 MB. - 400
test_mode_only—POST /screenings/{id}/advanceworks with a test key only (cp_test_…). - 503
test_mode_not_ready— Test mode isn’t available right now. Try again later, with a new Idempotency-Key. - 503
busy— Carousel is briefly at capacity. Retry after the seconds in theRetry-Afterheader; with the sameIdempotency-Keya send is never made twice. - 503
view_links_not_ready— View links aren’t available right now. Try again later. - 416 — The
Rangeheader is bad. Ask forbytes=0-4194303, then onward, within the file. - 422
unknown_combination— A well-formedchecksthat isn’t exactly one combination. Send exactly the checks of one combination, in any order —GET /checks?region=CAlists them. - 422
court_area_mismatch— Only a building in Québec refusescourt_roc. Sendcourt_qc,penal_qcor both for it. - 422
combination_unavailable— That combination isn’t set up to send there yet. Retry later, or send one whosesendableis true for your payer —GET /checks?region=CA. - 422
workflow_unavailable— That custom workflow isn’t offered where you’re sending, or its payer isn’t thepayeryou sent. Leavepayerout, use a workflowGET /checksoffers there, or retry later. - 429
rate_limited— Wait the seconds in theRetry-Afterheader, then retry. - 500
internal_error— Retry later. If it keeps happening, write to support with the time of the request. - 502
carousel_error— A provider or service behind Carousel didn’t answer. Nothing was sent or charged — retry with the same Idempotency-Key.
Limits
- 120 requests a minute per key.
- 30 screenings sent a minute per account — replays and refusals count too, all but a
400for a malformed body. Test sends have their own 30 a minute. - 30 reads a minute per key across results, transactions and documents.
- 120 view links a minute per key, apart from its 120 requests.
- 10 webhook tests a minute per account.
- Webhook deliveries: up to 300 a minute per address.
- 10 live keys and 10 test keys per account, counting its developers’ keys and connected assistants’.
Over a limit, the answer is 429 rate_limited with a Retry-After header in seconds. There are no other rate headers.
When to retry
- Retry
429,500,502,503 busyand409 request_in_progress— after anyRetry-After, with the same Idempotency-Key, so nothing sends twice. - Retry after fixing something
402(top up) — the same key works. - Retry later
422 combination_unavailableand422 workflow_unavailable, with the same key — or send another combination or workflow. - Don’t retry unchanged the 400s, 403s, 404s,
409 region_mismatchand other 422s: the same request gets the same answer. That includes403 not_allowedand the limited key’s400 invalid_request(“This key is limited to some workspaces — name a workspace or building.”). Fix the request. After a403 not_allowed, the limited key’s 400, a 404, a 409 or a 422, send it with a new Idempotency-Key — the old one keeps its answer, and a changed body with it is409 idempotency_conflict. A 400 for a malformed body never used the key. The full rule: Retrying safely.

