Errors

Failures return a stable machine-readable code:

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Invalid request",
    "details": {
      "formErrors": [],
      "fieldErrors": { "name": ["String must contain at least 1 character(s)"] }
    },
    "request_id": "req_4f2a9c1e8b7d4a5f9e3c2b1a8d7f6e5c"
  }
}

Switch on error.code, never on error.message. Codes are part of the contract; messages are written for humans and may be reworded without notice.

Every code

Status	Code	When
400	`INVALID_INPUT`	A query parameter or body field failed validation, the body was not valid JSON, or it exceeded the size limit.
401	`INVALID_TOKEN`	The Authorization header is missing or malformed, or the key is unknown, revoked, or expired. The message never says which.
402	`PLAN_LIMIT_REACHED`	Sending this invitation would exceed your plan quota for the current period.
403	`INSUFFICIENT_SCOPE`	The key is valid but lacks the scope this endpoint requires. The message states what’s needed, never what the key has.
404	`NOT_FOUND`	No such resource, it belongs to another organization, or the id is not a UUID. All three answer identically on purpose — the API will not confirm that an id exists somewhere else.
409	`CONFLICT`	The request conflicts with the current state of the resource.
429	`RATE_LIMITED`	The key exhausted its hourly quota, or too many failed authentication attempts came from your IP. Honour the `Retry-After` header.
500	`INTERNAL_ERROR`	A failure on our side. The body is deliberately generic; send us the `request_id` and we can find the exact call.

details appears on 400 INVALID_INPUT (naming the offending fields) and on 429 RATE_LIMITED (carrying the limit and reset). Treat it as diagnostic detail for logs and developers, not something to parse into user-facing copy.

The ones worth designing for

404 is deliberately ambiguous

A resource that doesn’t exist, one that belongs to another organization, and an id that isn’t a UUID all return the identical 404. The API will not confirm that an id exists somewhere you can’t see it.Practically: don’t treat 404 as “deleted”. It also means “never existed” and “not yours”.

402 means the plan quota is spent

Only POST /v1/assessments/{id}/invitations can return it — quota is consumed when an invitation is sent, not when an assessment is created.Surface it as an admin action (“your plan’s assessments for this period are used up”), not as a retryable failure. Retrying returns 402 until the period rolls over or the plan changes. Reproduce it in test mode by inviting limit@example.com.

429 carries Retry-After

Honour the Retry-After header (seconds) rather than inventing a backoff. details also carries limit and reset if you’d rather compute your own.A 429 can also come from repeated failed authentication from your IP, in which case it’s telling you to stop retrying a bad key.

500 is ours, and needs a request id

The body is deliberately generic — we don’t leak internals into responses. Everything needed to diagnose it is in the request_id, so log that and send it to us.Safe to retry with backoff. If it’s reproducible, it’s a bug; tell us.

Suggested handling

Code	Retry?	Do
`INVALID_INPUT`	No	Fix the request. `details` names the fields.
`INVALID_TOKEN`	No	Stop. Check the key is live, unexpired and unrevoked.
`PLAN_LIMIT_REACHED`	No	Alert an admin.
`INSUFFICIENT_SCOPE`	No	Mint a key with the scope the endpoint needs.
`NOT_FOUND`	No	Treat as absent. Don’t distinguish deleted from never-existed.
`CONFLICT`	Maybe	Re-read the resource; its state changed under you.
`RATE_LIMITED`	Yes	Wait `Retry-After`, then retry.
`INTERNAL_ERROR`	Yes	Exponential backoff. Keep the `request_id`.

There is no idempotency key yet, so a retried write can duplicate. Retrying a timed-out invitation create may invite the candidate twice. Guard retries on your side until idempotency ships.

Getting started

Core concepts

Hiring reports

Your workspace

Help

Every code

The ones worth designing for

Suggested handling

​Every code

​The ones worth designing for

​Suggested handling

Every code

The ones worth designing for

Suggested handling