Error Codes

When errors occur, ShipEngine gives you the information you need to successfully handle the error and resolve the problem. This page lists all the different error_source, error_type, and error_code values that you might get from ShipEngine, and how to handle them.

Error Handling

Before reading this page, you should first have an understanding of how ShipEngine communicates errors and how you should handle them. See the error handling guide to learn more.

Error Structure

Each error object inside the errors array has the following structure:

Property NameDescription
error_sourceIndicates where the error originated and/or who you should contact for support. Some errors come from third-party sources, such as shipping carriers or sales order sources. See the list of error sources for more details.
error_typeThe type of error. This can be used to handle all errors of a certain type the same way. See the /list of error types for details.
error_codeA code that indicates the specific error that occurred. See the list of error codes for details.
messageA description of the error. This is useful for logging or debugging, but you should not code against this field, as messages can change over time.
error-specific fieldsMany errors have additional fields that provide more context about the error. Theses fields can be used for additional programmatic error-handling behavior. But be sure your code allows for these fields to be null or absent.

Example Error

Here's an example of an error object. Notice that it has all the error fields, plus some error-specific fields like confirmation, carrier_id, carrier_code, and carrier_name.

1
2
3
4
5
6
7
8
9
10
{
"error_source": "shipengine",
"error_type": "business_rules",
"error_code": "confirmation_not_supported",
"message": "Adult signature confirmation is not supported by Australia Post.",
"confirmation": "adult_signature",
"carrier_id": "se-123456",
"carrier_code": "australia_post",
"carrier_name": "Australia Post"
}

Error Source

The error_source field indicates where the error originated. This lets you know whether you should contact ShipEngine for support or if you should contact the carrier or marketplace instead.

ValueDescription
shipengineThe error is from ShipEngine. If you have any questions or require support, please contact us
carrierThe error came from a shipping carrier (such as UPS, FedEx, DHL, etc). ShipEngine support may be able to help clarify the error for you, but if the problem is with your carrier account, then you will need to contact them directly.
order_sourceThe error came from an order source (such as Shopify, Ebay, WalMart, etc). ShipEngine support may be able to help clarify the error for you, but if the problem is with your seller account, then you will need to contact them directly.

Error Type

The error_type field indicates the type of error that occurred. Think of this as a broad category of error.

This field makes it easier to handle all errors of a certain type the same way. For example, you may choose to prompt the user whenever a validation error occurs, and you may choose to email your IT admins when a security error occurs.

ValueDescription
account_statusThere is a problem with your account. This may be your ShipEngine account or a third-party account. See the the error_source field to determine which account needs your attention.
securityA security error occurred. This will occur if your API key is invalid or expired, or if you attempt to perform an operation that is not permitted for your account.
validationSomething is wrong with the API request. This may be a syntax error, missing a required field, or an illegal value or combinatio of values. This error type always means that some change needs to be made to the request before retrying.
business_rulesThere was a business rule violation. Business rules are requirements or limitations of a system.

If the error_source is shipengine, then please read the relevant documentation to find out what limitations or requirements apply. Or contact our support for help.

If the error_source is carrier or order_source, then ShipEngine support may still be able to help clarify the problem or propose a solution, or you may need to contact the third-party for assistance.
systemAn unknown or unexpected error occurred in our system. Or an error occurred that has not yet been assigned a specific error_type. If you receive persistent system errors, then please contact our support or check our API status page to see if there's a known issue.

Error Code

The error_code indicates the specific error that occurred. You can use this field to write code that handles a specific error however you want. If you'd rather handle all error of a certain type the same way, then consider using the error_type field instead.

Unspecified Errors

Some errors have an error_code of unspecified, which means that we haven't yet assigned a code to that error. As our engineers encouter these errors, they assign them a code. So, over time, all unspecified errors will be replaced with more specific error codes.

This means that your error-handling code should not rely on the unspecified code. Instead, you should always treat this code as a fallback or catch-all error code.

ValueDescription
auto_fund_not_supportedOnly certain carriers support pre-paid balances. So you can only add funds to those carriers. If you attempt to add funds to a carrier that doesn't support it, then you'll get this error code.
batch_cannot_be_modifiedOnce a batch has started [processing]/reference/process-batch), it cannot be modified. Attempting to modify it will cause this error.
carrier_conflictYou attempted to perform an operation on multiple shipments from different carriers. Try performing separate operations for each carrier instead.
carrier_not_connectedThis error means that you're trying to use a carrier that hasn't been setup yet. You can setup carriers from your ShipEngine dashboard, or via the API.
carrier_not_supportedThe operation you are performing isn't supported by the specified carrier.
confirmation_not_supportedSome forms of delivery confirmation aren't supported by some carriers. This error means that the combination of carrier and delivery confirmation are not supported.
field_conflictThis error means that two or more fields in your API request are mutually exclusive or contain conflicting values. The error will include a fields array that lists the conflicting fields.
field_value_requiredA required field is missing or empty. The field_name property indicates which field is missing. Note that some fields are conditionally required, based on the values of other fields or the type of operation being performed.
forbiddenYou attempted to perform an operation that you don't have permissions to do. Check your API key to ensure that you're using the correct one. Or contact our support team to ensure that your account has the necessary permissions.
identifier_conflictA few parts of the ShipEngine API allow you to provide your own ID for resources. These IDs must be unique; otherwise, you'll get this error code.
identifiers_must_matchWhen updating a resource (such as a [shipment](/reference/update-shipment or warehouse), the ID in the URL and in the request body must match.
incompatible_paired_labelsWhen creating a return label, you can optionally pair it to an outbound_label_id. The outbound label must be from the same carrier as the return label.
invalid_addressThe mailing address that you provided is invalid. Try using our address validation API to verify addresses before using them.
invalid_billing_planYou attempted to perform an operation that isn't allowed for your billing plan. Contact our sales team for assistance.
invalid_charge_eventWhen creating a label or creating a return label, if you set the charge_event field to a value that isn't offered by the carrier, then you will receive this error. You can leave the charge_event field unset, or set it to carrier_default instead.
invalid_field_valueOne of the fields in your API request has an invalid value. The field_name property indicates which field is invalid.
invalid_identifierThis error is similar to invalid_field_value, but is specifically for ID fields, such as label_id, shipment_id, carrier_id, etc. The field_name property indicates which field is invalid.
invalid_statusThe operation you're attempting to perform is not allowed because the resource is in the wrong status. For example, if a label's status is "voided", then it cannot be included in a manifest.
invalid_string_lengthA string field in your API request is either too short or too long. The field_name property indicates which field is invalid, and the min_length and max_length properties indicate the allowed length.
label_images_not_supportedNot all carriers allow you to add custom images to labels. You can only set the label_image_id for supported carriers
meter_failureThis error indicates a problem with your FedEx account. Please contact FedEx to resolve the issue.
rate_limit_exceededYou have exceeded a rate limit. Check the the error_source field to determine whether the rate limit was imposed by ShipEngine or by a third-party, such as a carrier. If the rate limit is from ShipEngine, then consider using bulk operations to reduce the nuber of API calls, or contact our support team about increasing your rate limit.
request_body_requiredThe API call requires a JSON request body. See the corresponding documentation page for details about the request structure.
return_label_not_supportedYou may receive this error if you attempt to schedule a pickup for a return label.
subscription_inactiveYou may receive this error if you attempt to perform an operation that requires a subscription. Please contact our sales department to discuss a ShipEngine enterprise contract.
terms_not_acceptedSome carriers require you to accept their terms and conditions before you can use them via ShipEngine. If you get this error, then please login to the ShipEngine dashboard to read and accept the carrier's terms.
tracking_not_supportedThis error will occur if you attempt to track a package for a carrier that doesn't offer that service.
trial_expiredYou may receive this error if your free trial period has expired and you have not upgraded your account or added billing information.
unauthorizedYour API key is incorrect, expired, or missing. Check our authentication guide to learn more about authentication with ShipEngine.
unspecifiedThis error has not yet been assigned a code. See the notes above about how to handle these.
verification_failureWhen verifying your account (by email, SMS, phone call, etc.) this error indicates that the verification code is incorrect. Please re-start the verification process to get a new code.
warehouse_conflictYou attempted to perform an operation on multiple shipments from different warehouses. Try performing separate operations for each warehouse instead.
webhook_event_type_conflictShipEngine only allows you to have one webhook of each type. If you would like to replace a webhook with a new one, please delete the old one first.