API Guides

Errors and troubleshooting

Every typed error uses a single envelope.

1{
2  "error": {
3    "code": "version_conflict",
4    "message": "Authorization version does not match If-Match.",
5    "retryable": false,
6    "details": { "expectedVersion": 2, "actualVersion": 3 },
7    "issues": []
8  },
9  "requestId": "req_123"
10}

Use error.code for recovery logic. Use requestId when contacting support.

Common errors

StatusCodeRecovery
400bad_requestFix malformed headers or request shape. A common cause is invalid If-Match.
400final_submission_policy_requiredInclude policy.finalSubmission when creating an authorization.
401unauthorizedCheck the bearer token and environment.
403forbidden, insufficient_permissionsUse a key with access to the selected environment and organization.
404prior_authorization_not_foundThe authorization ID is unknown or not visible to this organization.
404provider_not_foundThe provider NPI is not registered to your organization.
404payer_not_foundThe payer ID is not in the catalog.
404file_not_foundThe file ID is unknown or not visible to this organization.
404access_grant_expiredCreate a fresh live-session or handoff access grant.
404access_grant_revokedRead the latest live session or handoff before requesting another grant.
404channel_session_lostThe backing payer-channel session is gone. Read the authorization and live session again.
409unsupported_routeNo serviceable route exists for the provider, payer, state, service type, and service code.
409provider_access_not_configuredThe route exists but Collate does not have configured provider access for it.
409idempotency_key_reusedUse a new create idempotency key or resend the exact original body.
409version_conflictRe-read the resource and retry with the current version if the action is still needed.
409prior_authorization_not_mutableThe authorization cannot be edited in its current state. Follow status and nextAction.
409prior_authorization_not_actionableThe action endpoint was called while the authorization was not actionable.
409prior_authorization_terminalThe authorization is terminal. Future writes are rejected.
409next_action_requiredNo current customer-owned action exists. Read the latest authorization.
409next_action_not_confirmable/confirm was called for a non-confirmable action such as resolve_requirements.
409requirements_not_satisfiedPatch answers or attach files for the returned requirements.
409review_staleRe-read the authorization and approve the current submission.reviewSnapshot.
409file_not_readyComplete the file before attaching it.
409file_not_usableUse a ready authorization_attachment file.
409manual_handoff_not_allowedCreate a handoff only for complete_payer_interaction.
409manual_handoff_not_activeThe handoff is not active; read it before retrying.
409manual_handoff_already_closedThe handoff is closed. Read the authorization for current truth.
409manual_handoff_review_approval_requiredSend the current accepted review snapshot ID when accepting the handoff.
409live_session_not_availableNo read-only live session can be granted right now. Poll GET /live-session.
409interactive_grant_not_allowedInteractive grants require an active manual handoff.
413payload_too_largeUpload a smaller file.
422request_validation_failed, invalid_answers, invalid_file_contentFix the field-specific validation issues.
503workflow_backend_unavailableRetry later. The orchestration backend is unavailable.

Debug a requires_action loop

If the authorization stays in requires_action, inspect:

  • nextAction.type
  • requirements.questions
  • requirements.documents
  • requirements.issues
  • submission.reviewSnapshot
  • activeManualHandoff

For resolve_requirements, the usual issue is an unanswered linkId, an invalid answer value, an uploaded file that was not completed, or an attachment that omitted the required documentTypes value.

Debug a missing confirmable action

Do not call /confirm unless nextAction.resolution.kind = confirm.

If nextAction.type = resolve_requirements, write answers or attachments. If nextAction.type = complete_payer_interaction, use manual handoff endpoints.

Debug processing

processing means Collate owns the next move. It can include portal work, requirement discovery, final-review preparation, submission, recovery, or manual-handoff reconciliation. Poll the authorization. Use live sessions only for read-only transparency.

Debug waiting_on_payer

waiting_on_payer means submission.payerReceipt is present and the payer has the next move. Keep polling until the payer asks for more information or a terminal decision is observed.

Contact support

Include:

  • environment
  • authorization ID
  • current status, nextAction, outcome, and version
  • submission.payerReceipt.referenceNumber, if present
  • request ID from the error response
  • approximate timestamp
  • sanitized request and response details

Do not send unsanitized PHI or credentials.