Payerworks writes and explains files; it sends nothing to a payer. Every file a route writes says transmitted: false, and is yours to send on your own connection. A test key is for invented data only, never a real patient.
Every refusal has one shape: an HTTP status, and a body { "error": { "code", "message", "request_id", ... } }. The code is what to act on; the message is the sentence for a person, and may name the field, the figure or the kind; the request id is the one to quote when you write to us. A refusal of a request with several items (claims, questions, rows) lists each item’s own problems inside it.
{ "error": { "code": "invalid_claims", "message": "One or more claims would be refused; nothing was written.", "claims": [ … ] } }What to retry
Retry only a wait: 429 (after the seconds retry-after names), 503, and 409 idempotency_in_flight, with the same Idempotency-Key. The JavaScript and Python clients do this for you, at most twice. Never retry a 400, a 404, a 422 or a 501 unchanged: they answer the same until the request changes, and a 501 code ending in _not_offered is a route switched off on this host.
Every code
The codes, grouped by where they are declared. A code is listed once, under the first part of the API that declares it, and means the same wherever it is answered.
Any route that reads a claim or a file
| Code | Status | What it means |
|---|---|---|
no_claim | 400 | The body has no claim: send claim (or claims) in the 837P shape the docs describe. |
too_many_claims | 400 | At most 100 claims a call. |
invalid_claims | 422 | One or more claims would be refused; nothing was written or run. Each claim's errors are listed. |
duplicate_reference | 422 | Two claims carry the same reference (patientControlNumber, CLM01); each must be unique so its answers match back. |
no_x12 | 400 | Send the file's text as x12. |
not_read_here | 422 | This file is a kind Payerworks recognizes but does not read here yet; the error names its kind. |
unrecognized_x12 | 422 | This is not an X12 file Payerworks reads; the message lists the kinds it reads. |
not_an_835 | 422 | This is not an 835 remittance. |
not_an_acknowledgment | 422 | This is not a 999, a 277CA or a TA1. |
invalid_code | 400 | An adjustment reason code is one to four digits, or a letter and digits (such as 45, A1 or B13), optionally after its group. |
invalid_category | 400 | A claim status category is a letter and up to two letters or digits, such as A1 or F2. |
invalid_path | 400 | The path holds a percent escape that does not decode (for example %E0 or a lone %). Encode the value with encodeURIComponent. |
invalid_sandbox_attachments | 422 | A 275 sent back to the sandbox cannot be read; nothing was run. Each problem is listed with its field. |
answered_by_the_door | 501 | This route reads your key's account, so only the hosted API answers it, never the engine run on its own (in a browser or a test). |
Any route that writes a file
| Code | Status | What it means |
|---|---|---|
invalid_sender_id | 400 | sender_id is your submitter id at the receiver: 2 to 15 letters, digits or spaces. |
invalid_receiver_id | 400 | receiver_id is the receiver's interchange id: 2 to 15 letters, digits or spaces. |
invalid_control_number | 400 | control_number is the interchange control number you track, a whole number from 1 to 999999999. |
invalid_usage | 400 | usage is "T" (test) or "P" (production). |
test_key_production_file | 403 | A test key writes test interchanges only (ISA15 = T). Use a live key for a production file. |
sandbox_test_only | 400 | A sandbox payer answers test interchanges only: usage is "T" or left out. |
invalid_query | 400 | A query parameter's name or value is over 200 characters, or holds a percent escape that does not decode. |
answer_too_large | 413 | This answer is larger than one response can carry: send less in each call (split the file, or send fewer claims or requests). |
file_too_large | 413 | This file holds more than one call can read: the error names what was counted (unit) and the most one call reads (limit). Split it and send each part in its own call. |
Any route that reads X12
| Code | Status | What it means |
|---|---|---|
mixed_functional_groups | 422 | This interchange holds functional groups of different kinds: send each kind in its own interchange, so no part of it goes unread. |
Eligibility: the eligibility routes
On Eligibility.
| Code | Status | What it means |
|---|---|---|
no_request | 400 | The body has no eligibility request: send requests (a list), request, or the request itself in the JSON shape the docs describe. |
too_many_requests | 400 | At most 100 eligibility requests a call. |
invalid_requests | 422 | One or more eligibility requests would be refused; nothing was written. Each request's errors are listed. |
duplicate_trace | 422 | Two requests in one file carry the same trace (controlNumber); each must be unique so its answer matches back. |
no_answer | 400 | Send the 271 as x12 (the file's text) or as json (the JSON answer). |
not_a_271 | 422 | This is not an X12 271 eligibility answer: send the 271 with its ISA envelope. |
not_a_271_json | 422 | This JSON is not an eligibility answer: it holds no plans, benefitsInformation, errors or subscriber. |
invalid_asked | 400 | asked is { service_type_codes: [codes], date_of_service: YYYYMMDD }, each optional. |
invalid_service_type | 400 | A service type code is one to three letters or digits, such as 30 or 98. |
invalid_aaa_code | 400 | A reject reason code (AAA03) is one or two letters or digits, such as 72 or T4. |
invalid_loop | 400 | loop is the loop the reason was returned in, such as 2100C or 2110D. |
invalid_include | 400 | include names what to add to the answer: answer (the normalized read of the 271). |
invalid_shape | 400 | shape names how the answer that include=answer adds is written: normalized (the default) or plans (the grouped JSON shape). |
Claim status: the claim-status routes
On Claim status.
| Code | Status | What it means |
|---|---|---|
no_inquiry | 400 | Send the claim status question as inquiry (or inquiries), in the JSON claim status shape. |
too_many_inquiries | 400 | At most 100 claim status questions a call. |
invalid_inquiries | 422 | One or more claim status questions would be refused; nothing was written. Each question's errors are listed. |
duplicate_inquiry_trace | 422 | Two questions in one file carry the same trace (encounter.trackingNumber); each must be unique so its answer matches back. |
no_claim_status_answer | 400 | Send the payer's claim status answer as x12 (a 277) or json (the JSON answer). |
ambiguous_answer | 400 | Send the answer once: as x12 or as json, not both. |
invalid_claim_status_json | 400 | json is the JSON claim status answer, an object with its claims list (or its errors). |
not_a_claim_status_answer | 422 | This is not a claim status answer Payerworks reads: send a 277 (005010X212) or the JSON answer. |
invalid_status_asked | 400 | asked describes the question you asked; one of its fields is not in the form it takes. |
not_a_claim_status_question | 422 | This is not a claim status question: send a 276 (005010X212) as x12, or the questions as inquiry or inquiries. |
invalid_status_code | 400 | A claim status code is one to five digits, such as 65 or 689. |
ambiguous_question | 400 | Send the claim status questions once: as inquiry or inquiries, or as x12 (a 276), not both. |
invalid_payer_name | 400 | payer_name is the payer's name as the 276 writes it (2100A NM103): text of at most 60 characters. |
invalid_submitter_name | 400 | submitter_name is your organization's name as the 276 writes it (2100B NM103): text of at most 60 characters. |
Remittances and denials: the denials routes
| Code | Status | What it means |
|---|---|---|
no_remittance | 400 | Send an 835 as x12, or the claims as a list in claims. |
two_inputs | 400 | Send either x12 (an 835) or claims (a list), not both. |
invalid_claim_facts | 422 | One or more claims or facts are not usable; nothing was decided. Each problem is listed with its field. |
invalid_letter_facts | 422 | One or more facts are not usable; nothing was written. Each is listed with its field. |
unknown_letter_kind | 400 | kind is one of the letter kinds the answer lists, with the facts each requires. |
missing_facts | 422 | The letter needs facts that were not sent; the answer lists them. |
letter_refused | 422 | The letter was not written: a fact holds a placeholder in brackets, which the guard refuses. |
invalid_letter | 400 | Send the letter's text as letter, at most 20000 characters. |
invalid_group_code | 400 | A claim adjustment group code is two letters, such as CO or PR. |
is_a_remark_code | 400 | This is a remittance advice remark code (RARC), not a claim adjustment reason code (CARC). |
Events and webhooks: the events routes
| Code | Status | What it means |
|---|---|---|
invalid_limit | 400 | limit is a whole number from 1 to 100. |
invalid_cursor | 400 | starting_after is the next_cursor of an earlier page, or the id of one of this key's events. |
invalid_event_type | 400 | type is one of the event types the developers page lists. |
invalid_event_id | 400 | An event id is evt_ followed by 16 to 64 lowercase hexadecimal characters. |
event_not_found | 404 | No event of this key has that id. Events are kept for 30 days. |
invalid_delivery_state | 400 | The delivery state filter names one of the states the developers page lists. |
invalid_created | 400 | created_gte and created_lt are instants written like 2026-10-19T14:00:00Z, and created_gte comes before created_lt. |
Acknowledgments: the claims routes
On Acknowledgments.
| Code | Status | What it means |
|---|---|---|
no_claims_to_track | 400 | Send the claims to track as claims (a list) or x12_837 (an 837P interchange, or a list of them). |
ambiguous_claims | 400 | Send the claims once: as claims or as x12_837, not both. |
invalid_track_request | 400 | A field of the request is not in the shape it takes; each problem is listed with its field. |
invalid_tracked_claims | 422 | One or more claims cannot be tracked; nothing was read. Each problem is listed with its field. |
not_a_tracked_file | 422 | A file is not a kind its list takes: x12_837 holds 837P claims, acknowledgments holds 999s, 277CAs and 277 requests for additional information, remittances holds 835s, attachments holds solicited 275s. The error names the file and its kind. |
too_much_to_track | 413 | More was sent than one call tracks: the error names what was counted (unit) and the most one call takes (limit). Send fewer claims or files a call. |
Enrollment: the enrollment-import routes
On Enrollment.
| Code | Status | What it means |
|---|---|---|
invalid_import | 422 | The CSV could not be read as an enrollment import, so no row was checked or saved. Each problem is listed; the columns are in the import template. |
export_takes_no_paging | 400 | An export holds every request that matches its filters, so it takes no limit or starting_after. |
export_too_large | 413 | Every request matching these filters does not fit in one export. Narrow the filters (a payer, a transaction, a created range) and export each part. |
Enrollment: the enrollments routes
On Enrollment.
| Code | Status | What it means |
|---|---|---|
invalid_provider | 422 | One or more provider fields would be refused; nothing was saved. Each problem is listed with its field. |
provider_exists | 409 | This key already has a provider with this NPI and tax id; the error names it. |
provider_limit_reached | 409 | A key holds at most 500 providers (a test key 50). Delete one you no longer use. |
invalid_provider_id | 400 | A provider id is prv_ followed by 24 lowercase hexadecimal characters. |
provider_not_found | 404 | This key has no provider with that id. |
provider_in_use | 409 | The NPI and tax id can no longer change: a request for this provider has gone to a payer. The error names those requests. |
provider_has_enrollments | 409 | This provider has requests that are open or live; cancel them first. The error names them. |
invalid_starting_after | 400 | starting_after is the next_cursor of an earlier page, or the id of an item on an earlier page. |
invalid_npi_filter | 400 | npi is the provider’s 10-digit NPI, with a valid check digit. |
invalid_tax_id_filter | 400 | tax_id is the provider’s 9-digit EIN, with or without the hyphen after the second digit. |
q_too_long | 400 | q is at most 100 characters. |
invalid_enrollment | 422 | One or more enrollment fields would be refused; nothing was saved. Each problem is listed with its field. |
enrollment_exists | 409 | This provider already has an open request for this payer and transaction; the error names it and its status. |
enrollment_limit_reached | 409 | A key holds at most 5,000 enrollment requests (a test key 500). Delete drafts and ended requests you no longer need. |
invalid_enrollment_id | 400 | An enrollment id is enr_ followed by 24 lowercase hexadecimal characters. |
enrollment_not_found | 404 | This key has no enrollment request with that id. |
enrollment_sent | 409 | This request has gone to the payer, so its fields can no longer change. Cancel it and file a new one. |
enrollment_ended | 409 | This request is canceled, rejected or ended; nothing more can change. File a new request. |
enrollment_not_deletable | 409 | Only a draft, canceled or rejected request can be deleted. Cancel it first. |
enrollment_not_draft | 409 | Only a draft is submitted; this request already was. |
invalid_cancel | 422 | reason is text of at most 200 characters, with no run of eight or more digits. |
invalid_status_filter | 400 | status is one or more of the eight enrollment statuses, separated by commas. |
invalid_transaction_filter | 400 | transaction is eligibility, claim_status, professional_claims or remittances. |
invalid_payer_filter | 400 | payer_id is 1 to 80 letters and digits. |
invalid_provider_filter | 400 | provider_id is prv_ followed by 24 lowercase hexadecimal characters. |
invalid_waiting_on_filter | 400 | waiting_on is you, provider, payerworks or payer. |
invalid_date_filter | 400 | A date filter is a day, YYYY-MM-DD, or an instant, YYYY-MM-DDTHH:MM:SSZ. |
invalid_task_id | 400 | A task id is tsk_, the enrollment’s 24 hexadecimal characters, an underscore and two digits. |
task_not_found | 404 | This key has no task with that id. |
task_not_open | 409 | This request is not waiting on the provider, so its tasks cannot change now. |
task_blocked | 409 | A task ranked before this one is still open; the error names it, its rank and who holds it. Tasks are finished in rank order. |
task_is_payerworks | 409 | This task is Payerworks’ to do, not the provider’s. It is shown so you can see what Payerworks is waiting on. |
invalid_task_values | 422 | One or more task values would be refused; nothing was saved. Each problem is listed with its field. |
invalid_document_request | 422 | Send task_id, field_key and filename (ending .pdf, at most 120 characters); each problem is listed with its field. |
field_not_a_document | 422 | That field of the task does not take a document. |
document_limit_reached | 409 | An enrollment request holds at most 20 documents. Delete one you no longer need. |
upload_unavailable | 503 | No upload address could be made just now; nothing was saved. Retry in a moment. |
invalid_document_id | 400 | A document id is doc_, the enrollment’s 24 hexadecimal characters, an underscore and 8 more. |
document_not_found | 404 | This key has no document with that id. |
upload_missing | 409 | Nothing has arrived at the upload address yet. Upload the PDF, then confirm again. |
not_a_pdf | 422 | The uploaded file is not a PDF (it does not start %PDF-). It was deleted; upload the PDF again. |
document_too_large | 422 | A document is at most 10 MB. It was deleted; upload a smaller PDF. |
document_not_uploaded | 409 | This document has not been uploaded and confirmed, so there is nothing to download. |
document_in_use | 409 | A completed task names this document. Reopen the task first (complete: false), then delete it. |
invalid_payer_id | 400 | A payer id is 1 to 80 letters and digits. |
sandbox_nothing_to_advance | 409 | The sandbox payer has no move to make now: the next move is yours, the request has ended, or this scenario never moves. The error says whose turn it is. |
changed_meanwhile | 409 | This request changed while yours ran, so nothing was saved. Send it again. |
Claims: the edits routes
On Claims.
| Code | Status | What it means |
|---|---|---|
invalid_edit_filter | 400 | A filter on GET /v1/edits is snip_type (1 to 7), severity (error or warning), kind (deterministic or code_set) or runs_in (edits, validateClaim, validateSecondaryClaim or correction-plan); the message names the one that is not. |
invalid_edit_code | 400 | An edit code is snake_case letters, digits and underscores, at most 64 characters, such as future_date. |
edit_not_found | 404 | No edit has this code: GET /v1/edits lists every edit Payerworks runs and the ones it does not. |
Claims: the corrections routes
On Claims.
| Code | Status | What it means |
|---|---|---|
invalid_change | 400 | change is "replace" (correct a claim) or "void" (cancel it). |
invalid_payer_claim_number | 400 | payer_claim_number is the payer's own number for the claim, at most 50 characters and none of the X12 delimiters (~ * : ^). |
payer_claim_number_needed | 422 | The payer processed the claim, so the plan needs its claim number: it is CLP07 on the 835, REF*1K on the 277CA, or the number a claim status answer gives. |
invalid_medicare_mac | 400 | medicare_mac is true or false. |
invalid_adjudicated | 400 | adjudicated is true or false: true says the payer processed the claim even when its number is not at hand. |
claim_type_not_planned | 422 | claim_type is "professional" or "dental": an institutional claim carries its frequency in the type of bill, which this plan does not cover yet. |
invalid_correction_claim | 400 | original and replacement are each one claim in the 837P JSON shape POST /v1/claims/837p takes. |
not_an_837p | 422 | An x12 read as claims (original_x12 and replacement_x12 on POST /v1/claims/correction-plan, x12 on POST /v1/claims/validate) is an 837P interchange (GS08 005010X222A1). |
several_claims_in_file | 422 | original_x12 and replacement_x12 each hold exactly one claim: split a bulk file with POST /v1/x12/parse first. |
adjudication_unknown | 422 | Say whether the payer processed the claim: send payer_claim_number (CLP07 on the 835, REF*1K on the 277CA) when it did, or adjudicated: false when it was rejected before processing (a 999 or 277CA rejection). Sending a processed claim again as a new one is a duplicate. |
not_an_837d | 422 | With claim_type dental, original_x12 and replacement_x12 are each a one-claim 837D interchange (GS08 005010X224A2). |
dental_not_checked_here | 422 | A dental claim sent as an 837D is read where the API runs (POST /v1/claims/correction-plan), not on this page: send it as JSON here, or call the API. |
Payer directory: the payers routes
On Payer directory.
| Code | Status | What it means |
|---|---|---|
payer_not_in_directory | 404 | The Payerworks directory holds no published facts about this payer. It lists payers and plan programs from public federal files, not every payer, and not the payers Payerworks can send to. |
not_a_directory_row_id | 400 | GET /v1/payers/{id} takes a directory row id (pwd_ and 16 hex), never a payer ID: search GET /v1/payers?q= to find a payer by its payer ID or name. |
invalid_payer_query | 400 | A search parameter is out of shape; the error names it in field (q, state, type, limit or starting_after). |
payer_directory_unavailable | 503 | The payer directory is not loaded where this was asked; the Payerworks API answers it. |
Claim status: the follow-up routes
On Claim status.
| Code | Status | What it means |
|---|---|---|
no_claims_to_follow | 400 | Send the open claims as claims (each with its reference, payer_id and sent_on), or the files as files (x12_837, acknowledgments, remittances). |
ambiguous_follow_up | 400 | Send the claims once: as claims or as files, not both. |
invalid_follow_up_request | 400 | A field of the request is not in the shape it takes; each problem is listed with its field. |
too_much_to_follow | 413 | More was sent than one call takes: the error names what was counted (unit) and the most one call takes (limit). |
Remittances and denials: the remittance-extras routes
| Code | Status | What it means |
|---|---|---|
no_remittances | 400 | Send the 835s as remittances: a list of X12 files, each the file's text. |
too_many_remittances | 413 | More was sent than one call reads across its files (at most 50 files, 1000 checks, 5000 claims, 5000 provider-level adjustments and 2000 deposits): the error names the unit and the limit. Send fewer in each call. |
deposits_required | 400 | Send the bank's deposits as deposits: a list of { amount, effective_date, trace_number?, originator?, description?, id? }. |
invalid_deposits | 422 | One or more deposits are not usable; nothing was matched. Each problem is listed with its field. |
invalid_split_by | 400 | by is "payee" (the 2000 loop's provider, TS301) or "rendering_npi" (each claim's rendering provider, NM1*82). |
value_holds_a_delimiter | 422 | A value in the file holds one of the characters Payerworks writes as a delimiter (* : ^ ~), so it cannot be copied unchanged; nothing was written. |
invalid_payer | 400 | Name the payer by its slug from GET /v1/filing-limits, or by its name. |
invalid_date_of_service | 400 | date_of_service is a day, YYYY-MM-DD. |
no_filing_limit_on_record | 404 | No published filing window is on record for this payer. Ask the payer, or read your agreement with it; GET /v1/filing-limits lists every payer that has one. |
Analytics: the analytics routes
On Analytics.
| Code | Status | What it means |
|---|---|---|
invalid_analytics_request | 400 | A field of the request is not in the shape this route takes; each problem is listed with its field. |
too_much_to_analyze | 413 | More was sent than one call reads: the error names what was counted (unit) and the most one call takes (limit). Send fewer files a call. |
nothing_to_summarize | 400 | Send the claims (claims or x12_837) with their acknowledgments and remittances, or the remittances alone. |
invalid_fee_schedule | 422 | One or more fee schedule rows are not usable; nothing was judged. Each problem is listed with its field. |
no_claim_to_check | 400 | Send the claim to check as claim, in the 837P JSON shape POST /v1/claims/validate takes. |
invalid_risk_claim | 422 | The claim cannot be compared: each problem is listed with its field. Nothing was read. |
invalid_outcomes | 422 | One or more appeal outcomes are not usable; nothing was ranked. Each problem is listed with its field. |
Eligibility: the eligibility-tools routes
On Eligibility.
| Code | Status | What it means |
|---|---|---|
no_identity_request | 400 | Send request (the eligibility request the payer refused, in the JSON POST /v1/eligibility/270 takes) and the reasons: reasons [{ code, loop }] or the refusing answer (x12 or json). |
invalid_identity_request | 422 | The request would be refused as a 270 before any retry is planned: its errors are listed. |
invalid_reasons | 400 | reasons is a list of { code, loop }: code an AAA reject reason (such as 75), loop where it was returned (such as 2100C), at most 20. |
invalid_known | 400 | known holds only text facts the caller gives: legal_first_name, previous_last_name, dependent_member_id, each at most 80 characters. |
no_reasons | 422 | Neither reasons nor the answer names a reject reason to plan from. |
no_answer_to_read | 400 | Send the 271 as x12 (the file’s text) or as json (either JSON eligibility answer). |
answer_not_read | 422 | An answer could not be read as an eligibility answer: send an X12 271 with its envelope, or a JSON eligibility answer. |
invalid_service_type_test | 400 | Send { baseline, specific, service_type_code, baseline_service_type }: two answers (x12 or json), the specific service type code asked, and the baseline asked (30, or 35 for dental). |
invalid_coordination | 422 | The coordination question would not be answered as sent: each problem is listed. |
invalid_discovery_verify | 400 | Send { patient: { first_name, last_name, date_of_birth, address?, previous_addresses?, gender? }, coverages: [answers, x12 or json], date_of_service? }. |
too_many_coverages | 400 | Verify at most 10 coverages a call. |
Prior authorization: the authorizations routes
| Code | Status | What it means |
|---|---|---|
no_authorization_request | 400 | The body has no review request: send requests (a list), request, or the request itself in the JSON shape the docs describe. |
too_many_authorization_requests | 400 | At most 100 review requests a call. |
invalid_authorization_requests | 422 | One or more review requests would be refused; nothing was written. Each request's errors are listed. |
duplicate_authorization_trace | 422 | Two review requests in one file carry the same trace (controlNumber); each must be unique so its response matches back. |
invalid_output | 400 | output is "x12" (the default), "fhir" (the Da Vinci PAS bundle shape) or "both". |
no_authorization_answer | 400 | Send the 278 response as x12 (the file's text), as json (Payerworks' own read of one) or as fhir (a Da Vinci PAS response Bundle or ClaimResponse). |
not_a_278 | 422 | This is not an X12 278 request for review and response (005010X217): send the 278 with its ISA envelope. |
not_a_278_response | 422 | This 278 holds requests only (BHT02 13): send the payer's response (BHT02 11). |
not_a_278_json | 422 | This JSON is not a read 278: it holds no reviews with a decision or a rejection. |
not_a_pas_response | 422 | This FHIR resource is not a PAS response: send a Bundle holding a ClaimResponse, or the ClaimResponse, with a reviewAction or an error. |
invalid_asked_requests | 400 | asked is the review request, or the list of them, that the response answers. |
invalid_explain_include | 400 | include names what to add to the answer: answer (the read of the 278). |
no_procedure_codes | 400 | Send procedure_codes: a list of HCPCS or CPT codes, such as L1833 or 64490. |
too_many_procedure_codes | 400 | At most 100 procedure codes a call. |
invalid_procedure_codes | 400 | Each procedure code is a HCPCS Level II code (a letter and four digits) or a five-character CPT code. |
invalid_payer_type | 400 | payer_type is medicare_fee_for_service, medicare_advantage, medicaid, commercial or other. |
invalid_state | 400 | state is the two-letter state the patient lives in, such as CA. |
invalid_setting | 400 | setting is hospital_outpatient or other (where the service is furnished), or left out. |
Patient estimates: the patient-money routes
| Code | Status | What it means |
|---|---|---|
no_estimate_lines | 400 | Send lines: the planned services, each with the allowed amount you expect (allowed_amount), at most 50 a call. |
too_many_estimate_lines | 400 | At most 50 estimate lines a call. |
invalid_estimate | 422 | The estimate request has fields that cannot be read; nothing was figured. Each problem is listed. |
member_required | 422 | This 271 answers more than one patient: send member_index to say which one to estimate. |
no_member | 422 | This 271 answers no patient to estimate. |
invalid_good_faith_estimate | 422 | The Good Faith Estimate is missing elements 45 CFR 149.610 requires, or has fields that cannot be read; nothing was laid out. Each problem is listed. |
no_dme_items | 400 | Send items: each { hcpcs, delivered_on }, at most 100 a call. |
too_many_dme_items | 400 | At most 100 items a call. |
invalid_dme_items | 422 | One or more items cannot be read; nothing was answered. Each problem is listed. |
invalid_fpl_request | 422 | The request has fields that cannot be read; nothing was figured. Each problem is listed. |
guideline_not_defined | 422 | The HHS poverty guidelines are not defined for Puerto Rico or the other territories; send use_contiguous_table: true if your program uses the contiguous table there. |
guideline_year_not_held | 422 | Payerworks holds the 2026 HHS poverty guidelines only; send guideline_year 2026 or leave it out. |
Documents and attachments: the documents routes
| Code | Status | What it means |
|---|---|---|
invalid_document_option | 400 | An option of this document is not one the route takes: the error names it and what it takes. |
too_many_forms | 400 | These claims need more CMS-1500 forms than one call draws (200, at six service lines a form): send fewer claims in each call. |
no_remittance_file | 400 | Send the 835 as x12 (the file's text). |
invalid_attachments | 422 | The 275 cannot be written as asked; nothing was written. Each problem is listed with its field. |
documents_unavailable | 503 | The PDF could not be drawn just now: the part of the API that draws it is not loaded. Retry in a moment. The engine run on its own, in a browser or a test, draws no PDF; the hosted Payerworks API, at the base URL shown with your key, does. |
unknown_appeal_form | 400 | form is redetermination (CMS-20027) or reconsideration (CMS-20033). |
invalid_appeal_form_input | 422 | One or more fields cannot be typed into the form; nothing was filled. Each problem is listed with its field. |
claim_not_on_remittance | 422 | The 835 holds no claim payment with this reference (CLP01); send the reference the denying claim payment carries. |
not_medicare_fee_for_service | 422 | These are Original Medicare's forms, and the 835 says this claim is not Medicare fee-for-service (CLP06 is not MA or MB): use the plan's own appeal, or POST /v1/appeals/letter. |
form_asset_changed | 503 | The form file on our side is not the one CMS published that we pinned, so nothing was filled. This is ours to fix. |
Documents and attachments: the model-reads routes
| Code | Status | What it means |
|---|---|---|
no_image | 400 | Send the file as base64: file_base64 for a paper EOB, front_base64 (and back_base64 if you have it) for an insurance card. |
invalid_image_base64 | 400 | The file is not base64: send the file's bytes base64 encoded (A-Z, a-z, 0-9, + and /, with = padding), with no data: prefix. |
image_too_large | 413 | The file is larger than one call reads: at most 1,400,000 bytes in all, before base64. Send a smaller copy (a lower resolution photo, or fewer pages). |
unreadable_image | 422 | The file could not be read as a picture or a PDF; the error says why (reason) and what to send instead. |
too_many_pages | 413 | The PDF holds more pages than one call reads: the error names the most (limit). Send fewer pages in each call. |
model_read_not_offered | 501 | Reading a document with a model is not offered on this host: Payerworks turns it on route by route. This is not a passing fault, so sending the request again answers the same. |
model_read_test_keys_only | 403 | This route answers test keys only, with invented documents, until an agreement covering the model is in place for live data. Use a test key. |
model_read_unavailable | 503 | The document reader could not be loaded just now, so nothing was read. Retry in a moment. The engine run on its own, in a browser or a test, has no reader; the hosted Payerworks API does. |
model_read_timed_out | 504 | The read did not finish inside one call's time. Send less: one page, or a crop of the part you need. |
model_read_failed | 502 | The reader gave no usable answer for this file, so nothing is answered from it. Send a clearer copy, or try again. |
not_an_eob | 422 | The reader did not see a payer's explanation of benefits or remittance advice in this file, so no draft was written. |
not_an_insurance_card | 422 | The reader did not see a health insurance card in this file, so nothing was looked up. |
model_read_daily_limit | 429 | This account's keys have made the most model-read calls an account may make on this route today (100 a UTC day, its keys together). Try again tomorrow. |
Claims: the sandbox-checks routes
On Claims.
| Code | Status | What it means |
|---|---|---|
invalid_seed | 400 | seed is your own string for the run, 1 to 64 of A-Z, a-z, 0-9, _ and -: the same seed, claims and start give the same run. |
invalid_instant | 400 | start and as_of are moments written in ISO 8601 with a time and a zone (such as 2026-10-19T09:00:00Z), from the year 2000 to 2099, and as_of is not before start. |
invalid_timeline_cursor | 400 | cursor is the next_cursor an earlier timeline answer gave, unchanged. |
cursor_other_run | 400 | This cursor belongs to another timeline run: the claims, the seed or the start differ from the run that made it. |
invalid_timeline_limit | 400 | limit is a whole number from 1 to 500. |
invalid_format | 400 | format is "x12", "report" or "both". |
timeline_not_offered | 501 | The sandbox timeline is not offered where this was asked: it is not connected to the claim checks here, so nothing was run. This is not a passing fault, so sending the request again answers the same. |
no_rules | 400 | Send the rules as rules, a list of one or more rule objects. |
too_many_rules | 400 | At most 100 rules a call. |
invalid_rules | 422 | One or more rules are not written in the rule format; nothing was applied. Each rule's problems are listed. |
no_mrf | 400 | Send the file's text as csv (the tall or wide CSV template) or the file as json (an object, or its text). |
mrf_too_large | 413 | The file is longer than 1990000 characters, or holds more than 50000 rows or 50000 items: check it in pieces, the first three rows sent again with each piece and row_offset set. |
mrf_not_json | 422 | json is not a JSON document that can be read. |
invalid_row_offset | 400 | row_offset is a whole number from 0 to 1000000000: the rows of the whole file before the first data row of this piece. |
Events and webhooks: the platform routes
| Code | Status | What it means |
|---|---|---|
invalid_destination_id | 400 | A destination id is wd_ followed by 16 lowercase hexadecimal characters. |
destination_not_found | 404 | This key has no webhook destination with that id. |
destination_limit_reached | 409 | A key holds at most 10 webhook destinations. Remove one to add another. |
invalid_destination_name | 400 | A destination's name is 1 to 80 characters. |
invalid_event_types | 400 | event_types is a list of the event types the developers page lists; an empty list, or leaving it out, receives every type. |
invalid_enabled | 400 | enabled is true or false, or left out. |
invalid_concurrency | 400 | concurrency is a whole number from 1 to 10: how many deliveries this destination takes at once. |
invalid_overlap_hours | 400 | overlap_hours is a whole number from 0 to 720: how long the old secret is still accepted after a rotation. |
destination_disabled | 409 | This destination is disabled. Enable it with PUT /v1/webhook-destinations/{id} and enabled: true first. |
destination_conflict | 409 | The destination changed while this request ran, so nothing was saved. Send the request again. |
not_at_destination | 404 | That event was never sent to this destination (it was made before the destination was added, or its type is filtered out). A ping or a new event will be. |
invalid_contact_email | 400 | email is an address of at most 254 characters, or null to remove it. |
contact_not_proved | 403 | Notices go only to an address Payerworks has proved: the one that asked for this account's test key by email and opened the link we sent. Send that address, or null to stop the notices. To use another, write to us from it. |
invalid_key_id | 400 | A key id is pwk_ followed by 16 to 40 letters and digits. |
key_not_found | 404 | This account has no key with that id. |
key_limit_reached | 409 | An account holds at most 3 test keys or 25 live keys that are not revoked. Revoke one to make another. |
invalid_key_name | 400 | A key's name is 1 to 80 characters. |
invalid_expires_in_days | 400 | expires_in_days is a whole number from 1 to 365, or left out for a key that does not expire. |
key_revoked | 409 | That key is revoked, so it cannot be rotated. Make a new key with POST /v1/keys. |
key_rotation_conflict | 409 | Another rotation of this key finished while this one ran, so this one made nothing: the secret that other request showed is the key's current one. List the keys with GET /v1/keys, and rotate again if that secret was lost. |
key_settings_out_of_range | 409 | The key's stored rate or account name is outside what a key may hold, so nothing was made or rotated; reason says which. Ask Payerworks to correct the key: sending the request again answers the same. |
SFTP file drop: the sftp routes
On SFTP file drop.
| Code | Status | What it means |
|---|---|---|
sftp_not_open | 403 | The SFTP file drop is not open on this Payerworks deployment. Every API route still answers. |
sftp_user_not_found | 404 | This key has no SFTP user. Make one with PUT /v1/sftp. |
invalid_acknowledgment_999 | 400 | acknowledgment_999 is "always", "errors_only", "never": when a 999 is written for a file you drop. |
unknown_sftp_field | 400 | PUT /v1/sftp takes acknowledgment_999 and nothing else. An SFTP user signs in with an SSH key only: add one with POST /v1/sftp/ssh-keys. |
invalid_ssh_public_key | 400 | public_key is one OpenSSH public key line (ssh-ed25519, ssh-rsa, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521), as the .pub file holds it. |
private_key_sent | 400 | That is a PRIVATE key. Nothing was kept: send the matching public key (the .pub file), and keep the private key on your own machine. |
ssh_key_limit_reached | 409 | An SFTP user holds at most 10 SSH keys. Remove one to add another. |
ssh_key_exists | 409 | This SFTP user already holds that SSH key. |
ssh_key_refused | 422 | The SFTP endpoint refused that SSH key, so nothing was added. Send another public key; an ssh-ed25519 key is the simplest. |
invalid_ssh_key_id | 400 | An SSH key id is key- followed by 17 lowercase hexadecimal characters, as GET /v1/sftp lists it. |
ssh_key_not_found | 404 | This SFTP user holds no SSH key with that id. |
sftp_unavailable | 503 | The SFTP user could not be read or changed just now, so nothing changed. Send the request again. |
Batch jobs: the jobs routes
On Batch jobs.
| Code | Status | What it means |
|---|---|---|
jobs_not_offered | 501 | Batch jobs are not offered on this host: Payerworks turns them on when they are ready. This is not a passing fault, so sending the request again answers the same. |
jobs_live_not_offered | 501 | Batch jobs answer test keys only for now, because a job keeps the request and its result for a while: use a test key, with invented data. |
invalid_job_route | 400 | route names the one route the job runs, as "POST /v1/claims/validate". A job runs: POST /v1/claims/validate, POST /v1/claims/837p, POST /v1/remittances/explain, POST /v1/eligibility/explain, POST /v1/claim-status/explain, POST /v1/analytics/summary, POST /v1/remittances/variance, POST /v1/claims/track, POST /v1/eligibility/270. |
invalid_job | 400 | A job is { route, query? }: route the one route it runs, query the query string every call carries (no leading ?), or left out. |
invalid_job_id | 400 | A job id is job_ and 24 letters or digits, as POST /v1/jobs answered it. |
job_not_found | 404 | No job of this key has that id. A finished job is kept 24 hours. |
job_not_cancellable | 409 | This job has already finished, so there is nothing to cancel: DELETE it to forget it now. |
job_running | 409 | This job is running: cancel it first (POST /v1/jobs/{id}/cancel), then delete it once it says canceled. |
jobs_daily_limit | 429 | This account's keys have made the most jobs an account may make today (50 a UTC day, its keys together). Try again tomorrow. |
Documents and attachments: the attachment-requests routes
| Code | Status | What it means |
|---|---|---|
no_information_request | 400 | Send the payer's 277 request for additional information as x12 (the file's text). |
not_an_information_request | 422 | This file is not a 277 request for additional information (005010X213): the error names what it is, and the route that reads it. |
no_requested_claims | 422 | This request holds no claim (no TRN in a patient loop), so there is nothing to say or check. |
invalid_information_request_call | 400 | A field of the request is not in the shape this route takes; each problem is listed with its field. |
no_attachment_response | 400 | Send the solicited 275 to check as x12_275: the file's text, or a list of them. |
not_an_attachment_response | 422 | A file sent as x12_275 is not a 275 this route can read: the error names the file and why. |
Keys and your account: the audit-log routes
| Code | Status | What it means |
|---|---|---|
invalid_audit_type | 400 | type is one of the audit log's entry types, or the part before its dot (key, webhook, enrollment...), as the developers page lists them. |
invalid_audit_cursor | 400 | starting_after is the next_cursor of an earlier page of this audit log. |
Organizations and members: the org routes
| Code | Status | What it means |
|---|---|---|
org_not_offered | 501 | Organizations and member sign-in are not open on this deployment yet. Keys still work as before. |
org_session_required | 401 | This route needs a member's console sign-in, not an API key. Sign in at payerworks.com/console. |
org_session_invalid | 401 | The sign-in could not be checked, or it has ended. Sign in again. |
org_session_not_accepted | 403 | A member's sign-in manages an account; it does not make this call. Call this route with an API key. |
org_email_not_verified | 403 | Confirm this sign-in's email address first: the code was emailed when the sign-in was made. |
org_choose | 400 | This sign-in belongs to several organizations: name one in the Payerworks-Organization header (GET /v1/org/memberships lists them). |
org_not_found | 404 | No organization with that id has this sign-in as a member. |
org_not_a_member | 403 | This sign-in belongs to no organization yet. Make one with POST /v1/org, or open an invitation's link. |
org_role_forbidden | 403 | Your role in this organization does not allow that. GET /v1/org/roles says which role does. |
org_owner_only | 403 | Only an owner may do that: invite or make an owner, change or remove an owner, revoke a removed member's keys, or change the organization's settings. |
org_last_owner | 409 | An organization always keeps at least one owner. Make another member an owner first. |
org_member_not_found | 404 | This organization has no member with that id. |
invalid_org_member_id | 400 | A member id is pwm_ followed by 16 lowercase hexadecimal characters. |
org_invitation_not_found | 404 | No pending invitation matches. It may have been accepted or canceled; ask for a new one. |
invalid_org_invitation_id | 400 | An invitation id is pwi_ followed by 16 lowercase hexadecimal characters. |
org_invitation_expired | 410 | An invitation's link works for 7 days. Ask a member of the organization for a new one. |
org_invitation_email_mismatch | 403 | This invitation was sent to another address. Sign in with the address the email reached. |
org_already_member | 409 | That person is already a member of this organization. |
org_invitation_pending | 409 | An invitation to that address is already waiting. Cancel it to send another. |
org_account_taken | 409 | That key's account already belongs to an organization. Ask one of its owners to invite you. |
org_key_not_usable | 403 | The api_key given is not a usable key (unknown, revoked or expired), so it proves no account. |
org_limit_reached | 409 | An organization holds at most 200 members and 50 pending invitations, and a sign-in belongs to at most 20 organizations. |
org_invitations_daily_limit | 429 | An organization sends at most 25 invitations a UTC day. Send more tomorrow. |
invalid_org_request | 400 | The request is not what this route takes: errors names each field and why. |
org_acting_key_required | 400 | Name the key this change is for in the Payerworks-Key header (its key id; GET /v1/org/keys lists them). |
org_acting_key_not_found | 404 | The organization's account has no usable key with that id. |
keys_managed_by_members | 403 | This account's organization chose that only its signed-in members manage keys. Make, rotate or revoke the key at payerworks.com/console. |
org_changed_meanwhile | 409 | The organization changed while this request was made. Read it again and send the change again. |
Claims: the submit routes
On Claims.
| Code | Status | What it means |
|---|---|---|
submit_not_offered | 501 | Payerworks does not send this claim yet: gates names each gate and whether it is open. Nothing was written or sent; write the 837P with POST /v1/claims/837p and send it on the connection you have. |
submit_envelope_assigned | 400 | On a submission Payerworks sets the interchange: leave out sender_id, receiver_id, the two qualifiers, control_number and usage. |
invalid_partner_id | 400 | partner_id is a partner's id as GET /v1/partners lists it, or left out to send to the one partner taking the claims' payer. |
reference_prefix_required | 422 | Every claim's patientControlNumber must begin with your account's reference prefix, so each answer can be matched to you alone; the error names the prefix and the claims. |
payer_not_at_partner | 422 | A claim names a payer this partner does not take claims for; send it in a call of its own to the partner that does. |
reference_in_flight | 409 | A claim with this patientControlNumber was already sent to this partner and has not been rejected; a corrected claim (frequency 7 or 8) may reuse it. |
submit_not_sent | 503 | The file was written but the partner's connection did not take it just now, so nothing was sent (transmitted: false). Send the call again. |
Every route: keys, limits, bodies and events
| Code | Status | What it means |
|---|---|---|
not_found | 404 | No such route. The routes are listed at payerworks.com/developers. |
method_not_allowed | 405 | This route does not answer that method; the allow header names the ones it does. |
no_key | 401 | Send your API key as Authorization: Bearer <key>. |
invalid_key | 401 | That key is not valid. Keys are issued by Payerworks; a revoked key stops within a minute. |
rate_limited | 429 | Over this key's calls a minute. Wait the seconds retry-after names. |
too_large | 413 | A request body may be at most 2 MB. |
invalid_json | 400 | The body must be a JSON object. |
invalid_idempotency_key | 400 | An Idempotency-Key is 1 to 255 visible characters, with no spaces, quotes or backslashes. A UUID is a good one. |
idempotency_key_reused | 422 | This Idempotency-Key was used in the last 24 hours for a different request. Send a new key for a new request. |
idempotency_in_flight | 409 | The first request with this Idempotency-Key is still running. Retry after the seconds retry-after names. |
idempotency_superseded | 409 | What this request set has since been changed or removed, so its answer cannot be given again. Send a new request with a new Idempotency-Key. |
internal | 500 | Something failed on our side. Retry; if it keeps failing, write to us with the request_id. |
store_unavailable | 503 | We could not read or write this key's records just now; the message says what was not done. Retry in a moment. |
queue_unavailable | 503 | We could not queue the events for delivery just now. Retry in a moment. |
invalid_webhook_url | 400 | A webhook address is https, at a public hostname, on port 443, with no login, at most 500 characters. |
invalid_rotate | 400 | rotate is true or false, or left out. |
webhook_conflict | 409 | The webhook changed while this request ran, so nothing was saved. Send the request again. |
no_webhook | 409 | This key has no webhook yet: set one with PUT /v1/account/webhook first. |
too_many_events | 413 | This run made more events than one delivery carries, so none were queued. Send fewer claims a call. |
webhook_rate_limited | 429 | Over this key's webhook deliveries a minute, so nothing was queued. Wait for the next minute. |
event_limit_reached | 429 | This account's keys have recorded the 2,000 events an account keeps in a UTC day, so no more are recorded or sent this UTC day. Events are recorded again from 00:00 UTC; an event refused before then is never sent by itself. |