Errors and status codes

Errors use standard HTTP status codes and a JSON body:

{
  "error": "case_not_found",
  "details": "Optional explanation you can show to a person."
}

error is a stable machine-readable code; match on it. details is human-readable and may change.

Validation errors

When a body or query string fails validation the status is 422 and the body lists each problem:

{
  "error": "validation_error",
  "details": "Some information is missing or invalid. Check the submitted fields and try again.",
  "issues": [
    { "code": "invalid_type", "field": "Business name" }
  ]
}

Each issue has a code (the kind of problem) and field (a readable field name). Some issues add details such as minimum, maximum or format.

Status codes

Status	Meaning
200	Success.
201	Created.
202	Accepted; the work continues in a background job.
400	The request is malformed or refers to something that does not fit, for example an assignee outside your workspace.
401	Missing, invalid or revoked API key.
403	The key is valid but not allowed to do this. See Authentication.
404	Not found, or not in your workspace. The API never confirms that another workspace’s IDs exist.
409	Conflict: the record changed since you read it, the case is closed, or an idempotency key was reused for a different request.
413	Upload too large (over 25 MB per file, or more than 25 files).
415	Unsupported file type. Upload PDF, PNG, JPEG or TIFF.
422	Validation failed.
429	Too many requests. See Rate limits.
5xx	Something went wrong on our side. Retry with backoff.

Common error codes

error	Status	What to do
invalid_api_key	401	Check the key; create a new one if it was revoked.
invalid_token	401	The Bearer value is not an API key. Send the rk_… key, or use the X-API-Key header.
interactive_user_required	403	Do this in the web app as a signed-in person.
review_required	403	An administrator or attorney reviewer must do this.
case_not_found	404	Check the case ID.
case_closed	409	The case is closed; reopen it in the web app first.
no_changes	400	Send at least one field to change.
invalid_assignee	400	The person is not an active member of your workspace.
rate_limited	429	Wait for Retry-After seconds, then retry.