Carousel docs
Tenant screening

Screening products

Tenant screeningThese docsCredit, criminal, eviction, income and ID for rental applicants.
Commercial screeningComing soonCredit, court records, ID and bank-verified income for commercial tenants and their guarantors.
Employment screeningComing soonID, police checks and Québec penal searches for candidates, and credit where the role calls for it.
Regular screeningComing soonBackground and identity checks for staff, members or contractors.
Developer guides · Carousel API

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 malformed checks: 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 only region gets it too: “This key is limited to some workspaces — name a workspace or building.”
  • 400 invalid_email — Send the applicant’s email address in applicant.email — phone numbers aren’t accepted.
  • 401 unauthorized — Send Authorization: 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 /workspaces says each one’s role and canSend. 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, /buildings or /screenings list 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 with after=0.
  • 409 region_mismatch — The region you 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}/advance works 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 the Retry-After header; with the same Idempotency-Key a send is never made twice.
  • 503 view_links_not_ready — View links aren’t available right now. Try again later.
  • 416 — The Range header is bad. Ask for bytes=0-4194303, then onward, within the file.
  • 422 unknown_combination — A well-formed checks that isn’t exactly one combination. Send exactly the checks of one combination, in any order — GET /checks?region=CA lists them.
  • 422 court_area_mismatch — Only a building in Québec refuses court_roc. Send court_qc, penal_qc or both for it.
  • 422 combination_unavailable — That combination isn’t set up to send there yet. Retry later, or send one whose sendable is 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 the payer you sent. Leave payer out, use a workflow GET /checks offers there, or retry later.
  • 429 rate_limited — Wait the seconds in the Retry-After header, 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 400 for 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 busy and 409 request_in_progress — after any Retry-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_unavailable and 422 workflow_unavailable, with the same key — or send another combination or workflow.
  • Don’t retry unchanged the 400s, 403s, 404s, 409 region_mismatch and other 422s: the same request gets the same answer. That includes 403 not_allowed and the limited key’s 400 invalid_request (“This key is limited to some workspaces — name a workspace or building.”). Fix the request. After a 403 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 is 409 idempotency_conflict. A 400 for a malformed body never used the key. The full rule: Retrying safely.

The infrastructureof yes.