Errors

Envelope

Successful responses return { "data": … }. Failures return an error object and a non-2xx HTTP status. Branch on the status code, not a body flag:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param",
    "message": "status must be one of TRACKING, NOT_TRACKING.",
    "param": "status",
    "details": {
      "issues": [{ "path": "status", "message": "status must be one of TRACKING, NOT_TRACKING." }]
    }
  }
}

Field	Notes
`type`	Broad category (see below).
`code`	Specific machine-readable code. Branch on this.
`message`	Human-readable; safe to surface in UI.
`param`	Offending field. Present on validation errors.
`details`	Optional structured detail (e.g. all validation `issues`).

Every response also carries an X-Request-Id header; include it when reporting an issue. Error responses repeat the code in an X-Croma-Error-Code header, so you can branch without parsing the body.

Types and codes

Status	`type`	`code`	Meaning
`400`	`invalid_request_error`	`invalid_param`	A query parameter or body field failed validation; see `param` / `details`. Unknown enum values, an unrecognized `city`, or an invalid export body land here.
`400`	`invalid_request_error`	`callback_unavailable`	Export callback delivery is temporarily unavailable. Wait inline or poll the status URL instead.
`401`	`authentication_error`	`invalid_api_key`	Missing or invalid key. See Authentication.
`401`	`authentication_error`	`personal_api_key_not_allowed`	A personal key was used; organization keys only.
`404`	`not_found_error`	`not_found`	No process with that id or radicado in your organization.
`404`	`not_found_error`	`job_not_found`	No export job with that id in your organization.
`404`	`not_found_error`	`endpoint_not_found`	No API endpoint at that path. See the API Reference.
`405`	`invalid_request_error`	`method_not_allowed`	Wrong method. Read endpoints are `GET`; exports are `POST`. The `Allow` header names the right one.
`429`	`rate_limit_error`	`rate_limited`	Quota exceeded; see Rate limits.
`500`	`api_error`	`internal_error`	Unexpected internal error. Retry, and contact support with the `X-Request-Id` if it persists.
`502`	`api_error`	`job_failed`	An export that was waited on inline failed.

A “no match” on a list is never a 404: searches and feeds return 200 with an empty data, and a defendant with no cases returns an empty list. Only the single-case endpoints (GET /v1/processes/{id} and its /actions) return 404, and only when the id or radicado isn’t in your organization. A case that exists but belongs to another organization also reads as 404.

Exports can also fail as a job rather than as an HTTP error: a polled or called-back job carries the same error object inside the envelope, with code: "job_failed".

Get Started

Guides

API Reference

Envelope

Types and codes

​Envelope

​Types and codes

Envelope

Types and codes