# Error Codes

When errors occur, ShipStation API 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 ShipStation API and how to handle them.

Before reading this page, you should first have an understanding of how ShipStation API communicates errors and how you should handle them. See [the error handling guide](/apis/shipengine/docs/guides/errors) to learn more.

> **TIP:**
### Error Logging
It is important to set up error logging for easier troubleshooting both locally and when contacting support. The `request_id` is the most important piece of information you can provide to help support locate your requests. For faster and more efficient troubleshooting, be sure to log this value from the response data.


## Error Structure

Each error object inside the [errors array](/apis/shipengine/docs/guides/errors#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](/apis/shipengine/docs/reference/errors-codes#error-source) for more details. |
| `error_type` | The type of error. This information can be used to handle all errors of a certain type in the same way. See the [list of error types](#error-type) for details. |
| `error_code` | A code that indicates the specific error that occurred. See the [list of error codes](#error-code) for details. |
| `message` | A description of the error. This information 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. These 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`.


```json
{
  "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 support](https://help.shipengine.com/hc/en-us/requests/new) or if you should contact the carrier or marketplace instead.

| Value | Description |
|  --- | --- |
| `shipengine` | The error is from ShipStation API. If you have any questions or require support, please [contact us](https://help.shipengine.com/hc/en-us/requests/new). |
| `carrier` | The error came from a shipping carrier (such as UPS, FedEx, DHL, etc). Our support team may be able to help clarify the error for you but if the problem is with your carrier account you will need to contact them directly. |
| `order_source` | The error came from an order source (such as Shopify, Ebay, WalMart, etc). Our support team may be able to help clarify the error for you but if the problem is with your seller account 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 ShipStation API account or a third-party account. See the the [error_source](#error-source) field to determine which account needs your attention. |
| `security` | A security error occurred. This will occur if your [API key](/apis/shipengine/docs/guides/auth#api-keys) 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 combination 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](#error-source) is `shipengine`, then please read the relevant documentation to find out what limitations or requirements apply. Or [contact our support](https://help.shipengine.com/hc/en-us/requests/new) for help.If the [error_source](#error-source) is `carrier` or `order_source`, then our support team 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 team](https://help.shipengine.com/hc/en-us/requests/new) or check our [API status page](https://status.shipengine.com) 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 errors of a certain type the same way, consider using the [`error_type`](#error-type) field instead.

> **NOTE:**
### 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](/apis/shipengine/docs/carriers/add-funds) to those carriers. If you attempt to add funds to a carrier that doesn't support it, you'll get this error code. |
| `batch_cannot_be_modified` | Once a [batch](/apis/shipengine/docs/labels/bulk) has started [processing](/apis/shipengine/docs/reference/process-batch) it cannot be [modified](/apis/shipengine/docs/reference/add-to-batch). 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_insurance_not_supported` | You attempted to purchase carrier insurance for a carrier that does not support that feature. Learn more about [insuring your shipments](/apis/shipengine/docs/shipping/insurance). |
| `carrier_not_connected` | This error means that you're trying to use a carrier that hasn't been [set up](/apis/shipengine/docs/carriers/setup) yet. You can set up carriers from your [account dashboard](https://dashboard.shipengine.com), or via [the API](/apis/shipengine/docs/carriers/connect). |
| `carrier_not_supported` | The operation you are performing isn't supported by the specified carrier. |
| `confirmation_not_supported` | Some forms of [delivery confirmation](/apis/shipengine/docs/shipping/delivery-confirmation) aren't supported by some carriers. This error means that the combination of carrier and delivery confirmation are not supported. |
| `customs_items_required` | The shipment object does not include customs but they are required for the shipment. Check out our [international shipping documentation](/apis/shipengine/docs/shipping/international). |
| `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](/apis/shipengine/docs/guides/auth#api-keys) to ensure that you're using the correct one. Or [contact our support team](https://help.shipengine.com/hc/en-us/requests/new) to ensure that your account has the necessary permissions. |
| `identifier_conflict` | A few parts of the ShipStation API allow you to [provide your own ID](/apis/shipengine/docs/shipping/create-a-shipment) for resources. These IDs must be unique, otherwise you'll get this error code. |
| `identifiers_must_match` | When updating a [resource](/apis/shipengine/docs/getting-started/rest#resources), like a [shipment](/apis/shipengine/docs/reference/update-shipment) or [warehouse](/apis/shipengine/docs/reference/update-warehouse), the ID in the URL and the request body must match. |
| `incompatible_paired_labels` | When [creating a return label](/apis/shipengine/docs/shipping/returns), 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](/apis/shipengine/docs/addresses/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](http://shipengine.com/pricing). [Contact our sales team](http://shipengine.com/contact) for assistance. |
| `invalid_charge_event` | When [creating a label](/apis/shipengine/docs/labels/create-a-label) or [creating a return label](/apis/shipengine/docs/shipping/returns), if you set the `charge_event` field to a value that isn't offered by the carrier 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_object` | You'll receive this error when there is an issue with a JSON object in your request that we are not able to identify more granularly. The `object` property indicates which object is invalid. |
| `invalid_status` | The operation you're attempting to perform is not allowed because the [resource](/apis/shipengine/docs/getting-started/rest#resources) is in the wrong status. For example, if a label's status is ["voided"](/apis/shipengine/docs/labels/voiding) it cannot be included in a [manifest](/apis/shipengine/docs/shipping/manifests). |
| `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](/apis/shipengine/docs/labels/branding). You can only set the `label_image_id` for [supported carriers](/apis/shipengine/docs/labels/branding#supported-carriers). |
| `meter_failure` | This error indicates a problem with your FedEx account. Please contact FedEx to resolve the issue. |
| `no_rates_returned` | This error means that there were no rates returned for the carrier referenced in the `carrier_code` field. |
| `rate_limit_exceeded` | You have exceeded a [rate limit](/apis/shipengine/docs/guides/rate-limits). Check the the [error_source](#error-source) field to determine whether the rate limit was imposed by ShipStation API or by a third-party, such as a carrier. If the rate limit is from ShipStation API, consider using [bulk operations](/apis/shipengine/docs/guides/rate-limits#bulk-operations) to reduce the number of API calls or [contact our support team](https://help.shipengine.com/hc/en-us/requests/new) about increasing your rate limit. |
| `request_body_required` | The API call requires a [JSON request body](/apis/shipengine/docs/getting-started/rest#json). See the corresponding documentation 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 team](http://shipengine.com/contact) to discuss the enterprise plan. |
| `terms_not_accepted` | Some carriers require you to accept their terms and conditions before you can use them via ShipStation API. If you get this error, please [log in to your account dashboard](https://dashboard.shipengine.com) to read and accept the carrier's terms. |
| `tracking_not_supported` | This error will occur if you attempt to [track a package](/apis/shipengine/docs/tracking/tracking) 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](/apis/shipengine/docs/guides/auth#api-keys) is incorrect, expired, or missing. Check our [authentication guide](/apis/shipengine/docs/guides/auth) to learn more about authentication with ShipStation API. |
| `unspecified` | This error has not yet been assigned a code. See the note 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` | ShipStation API only allows you to have one [webhook](/apis/shipengine/docs/tracking/webhooks) of each type. If you would like to replace a webhook with a new one, please [delete the old one first](/apis/shipengine/docs/reference/delete-webhook). |