Errors - Denialbase

Errors are JSON with an error message. Some add a stable code, and validation errors list every problem in errors.

{ "error": "This API key needs the claims:write scope" }

Status	When	Body
`401`	The `Authorization` header is missing, or the key is unknown, revoked or expired.	`error`
`403`	The key lacks the scope this endpoint needs.	`error`
`403`	Your practice has no signed business associate agreement.	`error`, `code: "baa_required"`
`403`	The organization can’t use the claims API (it isn’t an active practice).	`error`
`404`	`GET /api/v1/claims/status`: no claim with that `claim_number`.	`error`
`422`	The request is invalid. Nothing was saved.	`error`, `errors`
`429`	Too many requests. See Limits.	`error`, `retry_after`

Validation errors

A 422 lists every problem. In a batch, each message starts with the claim’s position, counting from 0. Messages name the field and never repeat what you sent.

{
  "error": "Invalid request",
  "errors": [
    "claims[1]: patient.date_of_birth is required (YYYY-MM-DD)",
    "claims[1]: claim.denial_codes or claim.denial_reason is required",
    "claims[3]: claim.claim_number appears more than once"
  ]
}

What a claim needs:

The patient’s first_name, last_name and date_of_birth.
claim_number (up to 128 printable characters, once per batch) and payer_claim_number (up to 128).
payer_name and date_of_service.
A billed_amount or denied_amount (positive).
denial_codes (up to 20) or a denial_reason.
Dates as YYYY-MM-DD, not in the future. plan_type, if you send it, from the documented list.

A refused claim inside a successful response

A claim whose claim number you already used for a different patient, or for a different claim of the same patient (another date of service or procedure code), doesn’t fail the request. It comes back in claims with created: false and an error, and the others are processed:

{
  "claims": [
    { "claim_number": "CLM-1003", "created": false,
      "error": "claim.claim_number is already used for a different patient" },
    { "claim_number": "CLM-1004", "created": false,
      "error": "claim.claim_number is already used for a different claim" }
  ],
  "submission_id": null
}

No signed business associate agreement

{
  "error": "A signed business associate agreement (BAA) with Coastal Ortho is required before any patient data can be received or sent.",
  "code": "baa_required"
}

Sign it in Settings → Agreements, then retry.