Skip to main content

Error Codes

A consolidated reference for the errors the Partners API returns, and how to resolve them.​

The Partners API returns standard HTTP status codes (see API Requests → Status Codes). For 400 and 422 responses, the body also includes a machine-readable errors array with a numeric code, a message, and field-level error_detail.

{
  "errors": [
    {
      "code": 42227,
      "message": "Invalid Address Zip",
      "error_detail": [{ "field": "zip", "message": "did not exist in the state provided" }]
    }
  ]
}

Duplicate / conflicting requests — 409​

A 409 Conflicting Request means your request conflicts with another recent request — most often a duplicate order submission. Because this is a pharmacy API, retrying a POST /orders call without checking can cause a duplicate fill.

{
  "error": {
    "error_code": 409,
    "message": "Your request is conflicting with another recent request. Please make sure this request is not a duplicate and resend."
  }
}

:::caution Make order submission idempotent Before retrying a failed or timed-out POST /orders, query GET /orders for the patient to confirm the order was not already created. Treat a 409 as "already in flight," not as a transient error to blindly retry. :::

Create order — 422 error codes​

Returned by POST /orders when the request is well-formed but cannot be processed.

Patient​

CodeMeaningResolution
42201Invalid Patient EmailProvide a valid email
42202Invalid Patient First NameProvide a valid first name
42203Invalid Patient Last NameProvide a valid last name
42204Invalid Patient PhoneProvide a valid phone
42205Invalid Patient GenderUse a valid gender code (M, F, N)
42206Invalid Patient IdVerify the patient_id from the RX_RECEIVED webhook
42208Invalid Patient Identity DocumentsControlled substance requires identity_documents

Identity documents​

CodeMeaningResolution
42216Invalid Document TypeOne of DL, PP, MI, PR, SI, TI, OT
42217Invalid Issuing Country2-character country code
42218Invalid Issuing State2-character state code
42219Invalid Document NumberProvide the document number
42220Invalid Document Expiration DateMust be future-dated, YYYY-MM-DD

Address​

CodeMeaningResolution
42221Invalid Address First NameProvide a valid first name
42222Invalid Address Last NameProvide a valid last name
42223Invalid Address Street1Provide a valid street address
42225Invalid Address CityProvide a valid city
42226Invalid Address State AbbreviationUse a 2-character state code
42227Invalid Address ZipZip malformed or not in the given state
42230Invalid AddressAddress could not be validated
42231Invalid Address StateState cannot be shipped to (licensure)

See Address Validation Errors for the full handling guide including suggested-address acceptance.

Items & prescription​

CodeMeaningResolution
42241Invalid Item NDCNDC not in your formulary
42242Invalid Item QuantityQuantity not offered for this product
42243Invalid Item Prescriber NameProvide a valid prescriber name
42244Invalid Item Prescriber PhoneProvide a valid prescriber phone
42245Invalid Item Prescriber FaxProvide a valid prescriber fax
42246Invalid Item GCNGCN not in your formulary
42247Invalid Item Package SizePackage size not offered
42249Invalid Item Prescription Idprescription_id invalid for partner-requested fills
42250Invalid Item Prescription RefillsPrescription has no refills remaining
42253Invalid Item InventoryNo remaining inventory
42254Invalid Item SKUSKU not in your formulary
42255Invalid Item Prescription QuantityRequested quantity exceeds the prescription
42256Invalid Item Shipping MethodShipping method not allowed for an item
42257Invalid Item Prescription ExpiredPrescription expired — a new Rx is required
42258Invalid Item Prescription NdcItem does not match medication on prescription
42259Invalid Item Written QuantityWritten quantity not offered for this product
42260Invalid Item Product SelectionItem not in your formulary

See Quantities and Package Sizes and Over-the-Counter Items.

Shipping & brand​

CodeMeaningResolution
42291Invalid Shipping Method IdUse an id from GET /shipping_methods
42292Invalid Shipping Signature ConfirmationNot available for the selected method
42293Invalid Shipping Method CarrierIncompatible with PO Box / general delivery
42294Invalid Shipping Label FormatLabel format invalid
42295Invalid Shipping Label ImpermissibleAccount not permitted to submit custom labels
42296Invalid Shipping Label DataLabel data does not match the format
42380Invalid Brandbrand_id did not match a brand for this account

Order action — 422 error codes​

Returned by POST /orders/{order_number}/partner_order_action_requests.

CodeMeaningResolution
42430Invalid Order Status Reason IdProvide a valid reason_id (refund events)
42461Invalid Order Action Eventevent not one of the supported values
42462Invalid Order Action RequestThis order cannot be verified through the API
42463Invalid Order for Action RequestThe event cannot be applied to this order's state