Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.trycollate.ai/llms.txt

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

Every error response uses a single envelope: 
{
  "error": {
    "code": "version_conflict",
    "message": "Authorization version does not match If-Match.",
    "retryable": false,
    "details": { "expectedVersion": 2, "actualVersion": 3 },
    "issues": []
  },
  "requestId": "req_123"
}
Match error.code to recover.

​
Error catalog

StatusCodeRecovery
400bad_requestCheck the request shape. The most common cause is a malformed If-Match header.
400final_submission_policy_requiredSend policy.finalSubmission on create.
401unauthorizedCheck the Authorization header and the API key for the selected environment.
404authorization_not_foundAuthorization ID is unknown to the organization.
404file_not_foundFile ID is unknown to the organization.
404provider_not_foundProvider NPI is not registered to the tenant.
404payer_not_foundPayer ID is not in the catalog.
409authorization_not_mutableThe authorization cannot be edited in its current state. Read the latest snapshot and follow status.
409authorization_not_confirmable/confirm was called while status was not requires_confirmation.
409next_action_required/confirm omitted nextActionId.
409next_action_mismatchThe nextActionId is stale. Read the latest authorization and retry with the current ID.
409next_action_not_confirmable/confirm was called for provide_requirements. Resolve that action with PATCH /answers or POST /attachments.
409requirements_not_satisfiedOutstanding blockers prevent confirmation. Patch answers and attach files.
409review_staleThe final review snapshot no longer covers the current authorization. Read the latest snapshot and re-approve. See Final submission approval.
409version_conflictIf-Match is stale. Read the latest authorization and retry with the current version.
409file_not_readyThe referenced file has not reached ready. Wait for completion.
409idempotency_key_reusedThe same idempotency key was reused with a different request body. Use a new key.
409unsupported_template_selectionNo serviceable route exists for the requested provider, payer, state, and service code.
422request_validation_failedRequest body, query parameters, headers, or portalAuthMode failed validation. The issues array points to each invalid field.

​
Where to look first

Start with the latest authorization snapshot:
  1. Read status, nextAction, and version.
  2. Read requirements for unresolved blockers.
  3. Read submission.payerReceipt and submission.decision for receipt and decision truth.

​
Common scenarios

​
Authorization stays in requires_input

At least one blocker is open. Inspect:
  • requirements.questions — unanswered or invalid questionnaire fields
  • requirements.documents — missing supporting documents
  • requirements.issues — validation errors
Resolve each through PATCH /answers or POST /attachments.

​
Authorization never moves to requires_confirmation

Usual causes:
  • a required canonical linkId was never answered
  • the attachment was uploaded but never completed
  • the file was completed but never linked
  • the linked file did not include the required document type in documentTypes

​
Authorization stays waiting_on_payer

waiting_on_payer means receipt is proven and the payer has the next move. It is not an error. Keep reading the authorization until the payer responds with more information needed or a terminal decision.

​
Asking for help

Email support@trycollate.ai and include:
  • environment (sandbox or production)
  • authorization ID
  • current status, outcome, and version
  • current nextAction, if present
  • submission.payerReceipt.referenceNumber, if present
  • approximate timestamp of the issue
  • sanitized request or response details
Avoid sharing unsanitized PHI or credentials.