Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.croma.run/llms.txt

Use this file to discover all available pages before exploring further.

​
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": "String must contain at least 3 character(s)",
    "param": "name",
    "details": { "issues": [{ "path": "name", "message": "String must contain at least 3 character(s)" }] }
  }
}
FieldNotes
typeBroad category (see below).
codeSpecific machine-readable code. Branch on this.
messageHuman-readable; safe to surface in UI.
paramOffending field. Present on validation errors.
detailsOptional structured detail (e.g. all validation issues).

​
Types and codes

StatustypecodeMeaning
400invalid_request_errorinvalid_paramBody failed validation; see param / details.
401authentication_errorinvalid_api_keyMissing or invalid key.
401authentication_errorpersonal_api_key_not_allowedA personal key was used; org keys only.
404not_found_errorresource_not_foundNo record in the upstream source.
405invalid_request_errormethod_not_allowedWrong method. Data endpoints are POST.
429rate_limit_errorrate_limitedQuota exceeded; see Rate limits.
500api_errorinternal_errorUnexpected internal error.
Not every endpoint emits every code. 404 only applies to lookups that resolve a specific record (e.g. Registraduría, SUNAT, RREE). Endpoints that proxy a flaky upstream (e.g. Rama Judicial) may return 502 with an upstream_error type. Each endpoint’s reference page lists its codes, and some upstreams use endpoint-specific code values.

​
Handling errors

Branch on the HTTP status first, then error.code for programmatic handling and error.message for display: 
const res = await fetch(url, options);
const body = await res.json();

if (!res.ok) {
  switch (body.error.code) {
    case "rate_limited":
      // back off using the Retry-After header, then retry
      break;
    case "resource_not_found":
      // treat as "no record", not a failure
      break;
    default:
      throw new Error(body.error.message);
  }
}

const { data } = body;
Include the X-Request-Id response header when reporting an issue. It lets us trace the exact request.