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 Name Description
error_source Indicates 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_type The 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_code A code that indicates the specific error that occurred. See the list of error codes for details.
message A 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 fields Many 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 of the error fields, plus some error-specific fields like confirmation, carrier_id, carrier_code, and carrier_name.

  "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.

Value Description
shipengine The error is from ShipEngine. If you have any questions or require support, please contact us
carrier The 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_source The 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.

Value Description
account_status There 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.
security A 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.
validation Something 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_rules There 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.
system An 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.

Value Description
auto_fund_not_supported Only 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_modified Once a batch has started processing, it cannot be modified. Attempting to modify it will cause this error.
carrier_conflict You attempted to perform an operation on multiple shipments from different carriers. Try performing separate operations for each carrier instead.
carrier_not_connected This 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_supported The operation you are performing isn't supported by the specified carrier.
confirmation_not_supported Some 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_conflict This 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_required A 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.
forbidden You 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_conflict A 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_match When updating a resource (such as a shipment or warehouse), the ID in the URL and in the request body must match.
incompatible_paired_labels When 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_address The mailing address that you provided is invalid. Try using our address validation API to verify addresses before using them.
invalid_billing_plan You attempted to perform an operation that isn't allowed for your billing plan. Contact our sales team for assistance.
invalid_charge_event When 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_value One of the fields in your API request has an invalid value. The field_name property indicates which field is invalid.
invalid_identifier This 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_status The 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_length A 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_supported Not all carriers allow you to add custom images to labels. You can only set the label_image_id for supported carriers
meter_failure This error indicates a problem with your FedEx account. Please contact FedEx to resolve the issue.
rate_limit_exceeded You 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_required The API call requires a JSON request body. See the corresponding documentation page for details about the request structure.
return_label_not_supported You may receive this error if you attempt to schedule a pickup for a return label.
subscription_inactive You 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_accepted Some 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_supported This error will occur if you attempt to track a package for a carrier that doesn't offer that service.
trial_expired You may receive this error if your free trial period has expired and you have not upgraded your account or added billing information.
unauthorized Your API key is incorrect, expired, or missing. Check our authentication guide to learn more about authentication with ShipEngine.
unspecified This error has not yet been assigned a code. See the notes above about how to handle these.
verification_failure When 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_conflict You attempted to perform an operation on multiple shipments from different warehouses. Try performing separate operations for each warehouse instead.
webhook_event_type_conflict ShipEngine 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.