Errors Guide

This guide provides an approach to identifying and managing errors encountered with EasyPost API operations. A clear understanding of the error framework and error handling are important for seamless integration and continuous operation.


Prerequisites


Key components

HTTP Status Codes

Errors are communicated through standard HTTP status codes with a JSON response detailing the issue.

  • 400 Bad Request: The request has invalid syntax for the given content type.
  • 401 Unauthorized: Required authentication by the authorization header has failed or is missing.
  • 404 Not Found: The action or resource was not found.
  • 422 Unprocessable Entity: The input was parsed correctly, but was invalid for another reason.
  • 500 Internal Server Error: An unexpected condition was encountered.
  • 503 Service Unavailable: A part of the service, or a third party that is required to complete the operation, is unavailable.

Error Response Structure

EasyPost's API returns error information in a structured JSON format. Each error includes:

  • code: A machine-readable string identifying the encountered error.
  • message: Describes the error in a human-readable string.
  • errors: An array of FieldError objects to provide specific details about the error.

Error Handling

Each client library will encapsulate errors and raise an exception. This includes both client and server errors, as well as exceptional cases such as network failures. It is recommended to handle exceptions gracefully; to report issues, please contact our Support team.

Catching an Error

POST /addresses
1curl -X POST https://api.easypost.com/v2/addresses \
2  -u "$EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5  "address": {
6    "street1": "..."
7  },
8  "verify_strict": "true"
9}'
Response
1{
2  "error": {
3    "code": "ADDRESS.VERIFY.FAILURE",
4    "message": "Address not found",
5    "errors": [
6      {
7        "field": "address",
8        "message": "Address not found",
9        "suggestion": null
10      },
11      {
12        "field": "street1",
13        "message": "House number is missing",
14        "suggestion": null
15      }
16    ]
17  }
18}

Error Codes

Below is a list of common error codes, along with their descriptions. This list does not encompass all possible error codes. For more detailed information, or additional assistance, please contact our Support team.

Code
Description
INTERNAL_SERVER_ERRORWe're sorry, something went wrong. If the problem persists please contact us at support@easypost.com.
NOT_ACCEPTABLEThe resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request.
NOT_FOUNDThe requested resource could not be found.
FORBIDDENUnable to access the requested resource.
PAYMENT_REQUIREDInsufficient funds. Please check your billing settings at https://www.easypost.com/account/settings?tab=billing.
UNAUTHORIZEDUnable to access the requested resource, authorization failed.
BAD_REQUESTMalformed request. Please check the contents and retry.
PAYMENT_GATEWAY.ERRORThe payment processor could not handle the request. Please try again or contact support@easypost.com if the problem persists.
MODE.UNAUTHORIZEDThis resource requires a production API Key to access.
MODE.CONFLICTAPI Key mode conflicted with parameter mode.
DATE.PARSE.FAILUREAt least one date was formatted incorrectly and could not be parsed.
PARAMETER.FORBIDDENThe request could not be completed due to forbidden properties present in the parameters.
PARAMETER.REQUIREDMissing required parameter.
ADDRESS.PARAMETERS.INVALID_CHARACTERThe parameters passed contained an invalid character.
ADDRESS.PARAMETERS.INVALIDThe parameters passed to create an Address were missing or invalid.
ADDRESS.COUNTRY.INVALIDInvalid 'country', please provide a 2 character ISO country code.
ADDRESS.VERIFICATION.NOT_FOUNDAddress Not Found.
ADDRESS.VERIFICATION.FAILUREThe address was unable to be verified.
ADDRESS.VERIFY.UNAVAILABLEAddress verification is not available. Please try again.
ADDRESS.VERIFICATION.INVALIDOne of the verifications selected is invalid.
ADDRESS.VERIFICATION.NOT_FOUNDAddress Not Found.
ADDRESS.VERIFY.FAILUREUnable to verify address.
ADDRESS.VERIFY.CARRIER_INVALIDUnable to verify address using provided carrier.
ADDRESS.VERIFY.UPSTREAM_UNAVAILABLEAddress verification is not available due to an upstream service not responding. Please try again.
ADDRESS.VERIFY.ONLY_USUSPS can only validate US addresses.
ADDRESS.VERIFY.INTL_NOT_ENABLEDInternational Verification not enabled on this account. Please contact support@easypost.com.
ADDRESS.VERIFY.MISSING_STREETInsufficient address data provided. A street must be provided.
ADDRESS.VERIFY.MISSING_CITY_STATE_ZIPInsufficient address data provided. A city and state or a zip must be provided.
BATCH.FILE_FORAMT.INVALIDInvalid required param: file_format.
BATCH.SHIPMENT.TOO_LARGEToo many shipments are attached to this batch.
BATCH.SHIPMENT.MISSINGOne or more shipments is required to perform this action.
BATCH.SHIPMENTS.REQUIREDInvalid request, 'shipments' are required.
BATCH.STATE.CREATINGUnable to modify batch while it is being created.
BATCH.STATE.CREATION_FAILEDOne or more of this batch's shipments has failed to be created.
BATCH.STATE.ALREADY_PURCHASEDThis batch is either already purchased or currently being purchased. If purchasing fails please try again at a later time.
BATCH.STATE.NOT_PURCHASEDOne or more of the shipments don't have postage associated to them.
BATCH.PARAMS.INVALIDUnable to create batch, one or more parameters were invalid.
BANK_ACCOUNT.CHARGE.FAILURECharge could not be created.
BANK_ACCOUNT.VERIFY.FAILUREBank account did not verify successfully.
CARRIER_ACCOUNT.REGISTRATION.FAILEDThe UPS Access License Request could not be completed.
CARRIER_ACCOUNT.PARAMETERS.INVALIDUnable to update carrier account, top level 'carrier_account' parameter was missing
CARRIER_ACCOUNT.INVALIDThe carrier account record was invalid and could not be saved.
CARRIER_ACCOUNT.TYPE.EXISTSThere is already a carrier account for that type
CARRIER_ACCOUNT.TYPE.UNKNOWNCarrier account type was unknown
CREDIT_CARD.CHARGE.FAILURECharge could not be created.
CREDIT_CARD.INVALIDThere was an issue connecting the card to the payment processor. Please try again.
CONTAINER.TYPE.INVALIDInvalid request, the 'type' provided is not one of our allowed values.
CONTAINER.DIMENSION.REQUIREDInvalid request, if one dimension is provided all three are required.
CONTAINER.NAME.REQUIREDInvalid request, 'name' is required.
CUSTOMS_INFO.PARAMETERS.INVALIDThe parameters passed to create a CustomsInfo were missing or invalid.
CUSTOMS_ITEM.ORIGIN_COUNTRY.REQUIREDThe Custom Item's origin country is required to proceed.
CUSTOMS_ITEM.CURRENCY.ONE_CURRENCY_SUPPORTEDInvalid request, only one 'currency' across all customs_items per customs_info supported.
CUSTOMS_ITEM.PARAMETERS.INVALIDThe parameters passed to create a CustomsItem were missing or invalid.
DOCUMENT.COMMERCIAL_INVOICE.FAILUREUnable to generate commercial invoice for shipment
DOCUMENT.CONVERSION.FAILUREUnable to convert document.
EMAIL_VERIFICATION.USEDThe code you submitted may no longer be used
EMAIL_VERIFICATION.NOT_FOUNDThe verification code you submitted could not be found
EMAIL_VERIFICATION.EXPIREDThe code you submitted is no longer valid, please use the most recent verification code that you have requested
IMAGE.CONVERSION.FAILUREImage conversion failed. Please retry or contact support@easypost.com
IMAGE.WIDTH.INVALIDImage width isn't a multiple of 8.
INSURANCE.PARAMETERS.INVALIDThe parameters you supplied were not valid for creating Insurance.
INSURANCE.CREATE.FAILUREWe were unable to create Insurance with the data provided.
INSURANCE.PURCHASE.NOT_ALLOWEDThe purchase of insurance is not allowed from this account.
INSURANCE.PURCHASE.FAILEDPurchasing insurance failed. Please retry or contact support@easypost.com.
INSURANCE.AMOUNT.BELOW_MINIMUMInsurance amount must be greater than 0
INSURANCE.AMOUNT.REQUIREDMissing required param: amount
INSURANCE.AMOUNT.ABOVE_MAXIMUMWe're sorry, the amount provided is greater than the maximum allowed.
ITEM.WEIGHT.REQUIREDInvalid request, 'weight' is required.
ITEM.HEIGHT.REQUIREDInvalid request, 'height' is required.
ITEM.WIDTH.REQUIREDInvalid request, 'width' is required.
ITEM.LENGTH.REQUIREDInvalid request, 'length' is required.
ITEM.VALUE.REQUIREDInvalid request, 'value' is required.
ITEM.NAME.REQUIREDInvalid request, 'name' is required.
ORDER.SHIPMENTS.REQUIREDInvalid request, if 'containers' or 'items' are not provided 'shipments' is required.
ORDER.FROM_ADDRESS.REQUIREDInvalid request, 'from_address' is required.
ORDER.TO_ADDRESS.REQUIREDInvalid request, 'to_address' is required.
ORDER.OPTIONS.INVALIDThe provided options are not valid.
ORDER.PARAMS.REQUIREDInvalid request, no parameters were included.
ORDER.INVALIDNot enough information was provided to create this order.
ORDER.RATE.UNAVAILABLEUnable to proceed, one of the shipments does not have the requested rate available to it.
ORDER.SERVICE.REQUIREDInvalid request, 'service' is required.
ORDER.CARRIER.REQUIREDInvalid request, 'carrier' is required.
ORDER.LABEL_DATE.INVALIDThe label_date option you provided is neither a valid ISO 8601 string, or a valid timestamp.
ORDER.CARRIER_ACCOUNTS.CONFLICTUnable to proceed, please provide specific carrier accounts in a list called 'carrier_accounts'.
PARCEL.PREDEFINED_PACKAGE.INVALIDThe specified predefined package for this parcel is invalid.
PARCEL.PARAMETERS.INVALIDThe parameters passed to create a Parcel were missing or invalid.
PICKUP.MIN_DATETIME.REQUIREDInvalid request, 'min_datetime' is required.
PICKUP.MAX_DATETIME.REQUIREDInvalid request, 'max_datetime' is required.
PICKUP.IS_ACCOUNT_ADDRESS.REQUIREDInvalid request, 'is_account_address' is required.
PICKUP.ADDRESS.INVALIDInvalid request, 'address' requires a valid 'street1', 'city', 'state', 'zip', 'phone', and 'name' or 'company'.
PICKUP.ADDRESS.REQUIREDInvalid request, 'address' is required.
PICKUP.REQUEST.INVALIDInvalid request, both batch and shipment cannot be supplied.
PICKUP.REQUEST.INVALIDError requesting pickup rates.
PICKUP.BATCH.INVALIDInvalid request, the provided 'batch' contains no shipments.
PICKUP.BATCH.REQUIREDInvalid request, a 'batch' of shipments is required.
PICKUP.SHIPMENT_SERVICE.INVALIDUnable to purchase pickup, one of your batch shipments has an invalid service.
PICKUP.BATCH_CARRIER.INCONSISTENTUnable to create pickup, the carrier associated with the batch shipments is inconsistent.
PICKUP.REQUEST.INVALIDInvalid request, a batch with shipments or a shipment is required to create a Pickup.
PICKUP.STATUS.INVALIDInvalid request, the pickup's current status does not allow this operation.
PICKUP.BUY.FAILEDWe're sorry, an error occurred scheduling the pickup.
PICKUP.BUY.NO_MATCHING_RATESUnable to purchase pickup, no rates matching your request were found.
PICKUP.SERVICE.REQUIREDInvalid request, 'service' is required.
PICKUP.CARRIER.REQUIREDInvalid request, 'carrier' is required.
PICKUP.SHIPMENT_COUNTRY.INVALIDUnable to purchase pickup, one of your batch shipments has an invalid to_address.country.
PICKUP.BUY.FORBIDDENUSPS pickup purchasing disabled in test mode
PICKUP.CANCEL.FAILEDWe're sorry, an error occurred cancelling the pickup.
PICKUP.CANCEL.FAILEDWe're sorry, an error occurred cancelling the pickup.
PICKUP.STATUS.INVALIDInvalid request, the pickup's current status does not allow this operation.
PICKUP.BUY.FAILEDWe're sorry, an error occurred scheduling the pickup.
PICKUP.BUY.NO_MATCHING_RATESUnable to purchase pickup, no rates matching your request were found.
PICKUP.SERVICE.REQUIREDInvalid request, 'service' is required.
PICKUP.CARRIER.REQUIREDInvalid request, 'carrier' is required.
PICKUP.SHIPMENT_COUNTRY.INVALIDUnable to purchase pickup, one of your batch shipments has an invalid to_address.country.
PICKUP.SHIPMENT_SERVICE.INVALIDUnable to purchase pickup, one of your batch shipments has an invalid service.
PICKUP.BATCH_CARRIER.INCONSISTENTUnable to create pickup, the carrier associated with the batch shipments is inconsistent.
PICKUP.REQUEST.INVALIDInvalid request, a batch with shipments or a shipment is required to create a Pickup.
PICKUP.REQUEST.INVALIDInvalid request, both batch and shipment cannot be supplied.
PICKUP.REQUEST.INVALIDError requesting pickup rates.
PICKUP.BATCH.INVALIDInvalid request, the provided 'batch' contains no shipments.
PICKUP.BATCH.REQUIREDInvalid request, a 'batch' of shipments is required.
PICKUP.ADDRESS.INVALIDInvalid request, 'address' requires a valid 'street1', 'city', 'state', 'zip', 'phone', and 'name' or 'company'.
PICKUP.ADDRESS.REQUIREDInvalid request, 'address' is required.
PICKUP.IS_ACCOUNT_ADDRESS.REQUIREDInvalid request, 'is_account_address' is required.
PICKUP.MAX_DATETIME.REQUIREDInvalid request, 'max_datetime' is required.
PICKUP.MIN_DATETIME.REQUIREDInvalid request, 'min_datetime' is required.
REFUND.NO_RESPONSEThe carrier did not respond to our refund request. Please try again or contact support@easypost.com
REFUND.FAILUREUnable to refund postage.
REFUND.TRACKING_CODES.INVALIDUnable to proceed, 'tracking_codes' are missing or invalid.
REFUND.TRACKING_CODE.NOT_FOUNDUnable to locate 'tracking_code' in your purchased shipment history.
SCAN_FORM.FAILUREScan Form generation failed. Please try again or contact support@easypost.com
SCAN_FORM.BATCH.MULTIPLE_CARRIERSUnable to create a ScanForm from a batch that was not bought from the same carrier.
SCAN_FORM.BATCH.NOT_PURCHASEDAll shipments on the Batch must be purchased before generating a ScanForm.
SCAN_FORM.SHIPMENTS.INVALIDA consistent from_address is required to create a USPS ScanForm.
SCAN_FORM.SHIPMENTS.REQUIREDPlease provide a valid list of shipments.
SCAN_FORM.CREATE.CARRIER_NOT_SUPPORTEDUnable to create a ScanForm from shipments bought from this carrier.
SCAN_FORM.CREATE.FAILUREThe scan form could not be created.
SHIPMENT.PURCHASE.FAILUREShipment purchase failed. Please try again or contact support@easypost.com
SHIPMENT.OPTIONS.INVALIDThe provided options are not valid.
SHIPMENT.INVALID_PARAMSUnable to create shipment, one or more parameters were invalid.
SHIPMENT.INVALIDNot enough information was provided to create this shipment
SHIPMENT.POSTAGE.INVALID_FORMATInvalid file_format type.
SHIPMENT.POSTAGE.FORMAT_UNAVAILABLEThe current label cannot be converted to the requested image format.
SHIPMENT.POSTAGE.REQUIREDPostage is required to complete this operation.
SHIPMENT.POSTAGE.EXISTSPostage already exists for this shipment.
SHIPMENT.POSTAGE.NO_RESPONSEUnable to complete shipment purchase: carrier is not responding to our request. Please try again or contact support@easypost.com
SHIPMENT.POSTAGE.FAILUREWe're sorry, an error has occurred while generating your shipping label. Please retry or contact support@easypost.com.
SHIPMENT.REFUND.UNAVAILABLEUnable to request refund. If this shipment is part of an order, please try refunding the first shipment from the order.
SHIPMENT.REFUND.UNAVAILABLEUnable to request refund for shipment without a postage label.
SHIPMENT.REFUND.FAILUREWe're sorry, an error occurred while generating your shipping label. Please retry or contact support@easypost.com.
SHIPMENT.CUSTOMS_INFO.DESCRIPTION_REQUIREDEach Customs Item must contain a description.
SHIPMENT.CUSTOMS_INFO.REQUIREDUnable to proceed, 'customs_info' is required for international shipments, shipments bound for US military bases, or US territories. Please see https://docs.easypost.com/docs/customs-infos for more information.
SHIPMENT.POSTAGE.TIMED_OUTUnable to complete shipment purchase: carrier timed out responding to our request. Please try again or contact support.
SHIPMENT.RATE.CARRIER_ACCOUNT_INVALIDThe rate you are attempting to purchase belongs to an inactive or inaccessible carrier account. You must create a new shipment or regenerate rates.
SHIPMENT.CARRIER_ACCOUNTS.CONFLICTUnable to proceed, please provide specific carrier accounts in a list called 'carrier_accounts'.
SHIPMENT.TRACKING_CODE.INVALID_CARRIERFailed to create shipment from tracking code, unsupported carrier.
SHIPMENT.INSURANCE.ALREADY_PURCHASEDThe shipment is already insured.
SHIPMENT.MISSING_RATEA valid rate must be supplied in order to purchase a shipment. Please verify the rate exists and that the rate is associated with the shipment being purchased.
SHIPMENT.MISSING_INFORMATIONA valid to_address, from_address and parcel must be present before attempting to purchase a shipment.
SHIPMENT.PURCHASE.IN_PROGRESSThe purchase process has already started for this shipment.
SHIPMENT.RATES.UNAVAILABLEMissing required data to get rates.
SHIPMENT.RATE.STAMP_UNAVAILABLEUnsupported Service & Carrier Combination
SHIPMENT.RATE.BARCODE_UNAVAILABLEUnsupported Service & Carrier Combination
SHIPMENT.POSTAGE.ASCIIThe ascii label format is disabled for production shipments.
SHIPMENT_REPORT.DATE_RANGE.INVALIDInvalid date range given for the shipment report
SHIPMENT_REPORT.ALREADY_IN_PROGRESSThe report for the given parameters is already being generated.
SHIPMENT_REPORT.DATE_RANGE.TOO_LONGThe date range covers more than 31 days
TRACKER.RETRIEVE.ERRORThe tracker(s) could not be retrieved, please try again.
TRACKER.RUN.ERRORThe tracker could not be executed, please try again.
TRACKER.CREATE.ERRORThe tracker could not be created, please try again.
TRACKER.NOT_FOUNDThe tracker(s) could not be found.
TRACKER.INVALID_TEST_CODEIn test mode, only test tracking numbers are valid. Test tracking numbers are EZ1000000001, EZ2000000002, ... , EZ7000000007
TRACKER.NO_CARRIER_ACCOUNTUnable to create tracker, please double check that you have the associated carrier account linked to your EasyPost account.
TRACKER.INVALID_PARAMSThe parameters you provided are invalid.
TRACKER.UNSUPPORTED_CARRIERThe carrier you have provided is not supported by EasyPost. Please confirm the carrier is entered correctly and is currently supported.
TRACKER.CARRIER_CODE_MISMATCHThe tracking number does not belong to the carrier you specified. Please confirm that both the carrier and tracking number are correct.
TRACKER.MULTIPLE_CARRIERS_FOR_CODEThe tracking number could belong to more than one carrier. Please specify carrier when creating your tracker.
TRACKER.NO_CARRIER_FOR_CODEThe tracking number doesn't seem to match the format for any carrier we currently support. Please check that you are sending a valid tracking number.
USER.UNAUTHORIZEDThe logged-in user does not have permission to access this resource.
USER.INVALIDThe user record was invalid and could not be saved.
USER.PARENT.INVALIDSub-accounts may not be added to records that are themselves sub-accounts.
USER.CHARGE.NOT_ALLOWEDPlease contact support@easypost.com to get one-time charges approved for your account.
WEBHOOK.EVENT.INVALIDThe event type of the received webhook could not be mapped to a handler.
WEBHOOK.INVALIDThe webhook record was invalid and could not be saved.
DHLGM.RATE_TABLE.NOT_FOUNDRate table was not found.
DHLGM.SCAN_FORM.GENERATION_FAILEDUnable to generate DHL Global Mail closeout. Please try again or contact us at support@easypost.com
DHLGM.RETURN.AUTHORIZATION_NUMBER_REQUIREDTo generate a DHL Global Mail return you must supply your return authorization number within the shipments print_custom_1 option.
DHLGM.LABEL.FAILUREUnable to generate DHL Global Mail shipping label. Please try again or contact us at support@easypost.com
DHLGM.NO_INTERNATIONALDHLGlobalMail does not support international shipments.
DHLGM.NO_ALCOHOLDHLGlobalMail does not permit the shipment of alcohol.
DHLGM.GIRTH_MAXYour parcel exceeds the maximum allowed girth of 84.
DHLGM.LETTER_NOT_SUPPORTEDDHL Global Mail does not support sending lettermail domestically. Use USPS First Class instead.
DHLGM.ACCESS_TOKEN.GENERATION_FAILEDUnable to generate DHL Global Mail access token. Please try again, or contact us at support@easypost.com

Address Verification Error Codes

Code
Description
E.COUNTRY.UNSUPPORTEDThis country is not supported in this mode. Try in production mode.
E.ENGINE.UNAVAILABLENo verification engine is available to service this country. Please try again later.
E.QUERY.UNANSWERABLEWe can not provide enough data in this country to satisfy this request. Please try again later.
E.ADDRESS.NOT_FOUNDAddress not found.
E.SECONDARY_INFORMATION.INVALIDInvalid secondary information(Apt/Suite#). Please note, this can show up as an error on a successful request.
E.SECONDARY_INFORMATION.MISSINGMissing secondary information(Apt/Suite#). Please note, this can show up as an error on a successful request.
E.HOUSE_NUMBER.MISSINGHouse number is missing.
E.HOUSE_NUMBER.INVALIDHouse number is invalid.
E.STREET.MISSINGStreet is missing.
E.STREET.INVALIDStreet is invalid.
E.BOX_NUMBER.MISSINGBox number is missing.
E.BOX_NUMBER.INVALIDBox number is invalid.
E.ADDRESS.INVALIDInvalid city/state/ZIP.
E.ZIP.NOT_FOUNDZip not found.
E.ZIP.INVALIDZip invalid.
E.ZIP.PLUS4.NOT_FOUNDZip + 4 not found.
E.ADDRESS.MULTIPLEMultiple addresses were returned with the same zip.
E.ADDRESS.INSUFFICIENTInsufficient/incorrect address data.
E.ADDRESS.DUALDual address.
E.STREET.MAGNETMultiple response due to magnet street syndrome.
E.CITY_STATE.INVALIDUnverifiable city / state.
E.STATE.INVALIDInvalid State.
E.ADDRESS.DELIVERY.INVALIDInvalid delivery address.
E.TIMED_OUTExceeded max timeout.
E.TIME_ZONE.UNAVAILABLEThe time zone service is currently unavailable.
E.PO_BOX.INTERNATIONALCannot verify international PO Box. Please note, this can show up as an error on a successful request.

Additional Resources

Support and Troubleshooting

In addition to the guidance provided in our Guides, EasyPost offers support to assist with FAQs, troubleshooting issues, and inquiries related to the EasyPost platform.

Please visit the Help Center for more information.