Skip to content
Red Folder Research — API Documentation

Errors

  • 400 — validation. Validation errors use two alternative shapes, never combined in one response. Field validation failures — each offending field maps to a list of messages:
{
  "plaintiff_name": ["This field is required."]
}

Cross-field rule violations (the conditional-requirement rules — “required when”, “at least one of”, etc.) arrive under non_field_errors, and are returned only once field-level validation passes:

{
  "non_field_errors": [
    "Fields 'policy_number' and 'claim_number' can not both be empty.You must define one (or both) of the fields."
  ]
}
  • 400 on GET /api/v1/partner/invoices/ — {"error": "invalid_filter", "detail": "<what to fix>"}. See Invoices.
  • 401 — missing or bad token. No Authorization header: {"detail": "Authentication credentials were not provided."}. Header present but the token is invalid or expired: {"detail": "Invalid token."}.
  • 403 — not currently returned by the partner API. Every partner endpoint only requires an authenticated user; cross-organization access to a case is reported as 404 (below), not 403, so as not to leak whether a case exists outside your organization.
  • 404 — unknown case_ref, a case your organization can’t access, or results not yet available on the results endpoint.
  • 409 — two sources with different bodies. Cancel returns it for a non-cancellable state (already closed, substantially complete, or intake still processing) with an error-keyed body — see the endpoint’s schema for the specific error code. The file-append endpoint returns it when the per-case cap is reached (25 files or 500 MB total per case) with a detail-keyed body: {"detail": "Per-case file limit reached (25 files / 524288000 bytes)."}. Files sent when replying to a case.action_required interaction are not counted against this cap.
  • 413 — request body too large. A backstop you will normally never observe: bodies above the ceiling are rejected at our network edge first, with a generic 413/502 that carries neither of the fields below. The coded form appears only when an oversized request reaches Red Folder directly — for example if edge configuration changes, or on a request that reaches our origin without passing through the edge. The edge and application ceilings are currently the same 200 MB of total body, so in normal operation the edge rejects first. Body: {"detail": ..., "error_code": "request_too_large"}. It is returned by every upload endpoint (case create, file append, interaction response, and the deprecated upload route), so branch on the code rather than the endpoint. Split the upload into smaller requests, or reduce file sizes, and see Size limits for the ladder and recovery steps.
  • 429 — rate limited. Most endpoints allow 100/min per authenticated user; the file-append endpoint (POST .../cases/{case_ref}/files) is capped separately at 60/min, and the two invoice endpoints (GET .../invoices/) share their own 60/min limit. Body: {"detail": "Request was throttled. Expected available in <N> seconds."}. Honor Retry-After when present and retry with exponential backoff.
  • File-level failures are reported differently by endpoint: case creation reports each file’s outcome per-file in the attachments array via error_code — the case itself still succeeds. The single-file append endpoint instead fails the whole request with 400 and {"detail": ..., "error_code": ...}. See each endpoint’s error_code table. A file over the 150 MB per-file limit carries error_code: file_too_large in either shape; a create request over 10 files or 192 MB of file bytes fails as a top-level files field error instead. Interaction responses (POST .../cases/{case_ref}/respond/) validate their attachments the same way and return the same {"detail": ..., "error_code": ...} envelope. Full ladder: Size limits.