{"templateId":"markdown","versions":[{"version":"shipstation-v2","label":"ShipStation V2 API","link":"/apis/shipstation-v2/docs/guides/errors","default":true,"active":false,"folderId":"58c9a61d"},{"version":"shipengine","label":"ShipStation API (formerly ShipEngine)","link":"/apis/shipengine/docs/guides/errors","default":false,"active":true,"folderId":"58c9a61d"},{"version":"shipstation-v1","label":"ShipStation V1 API","link":"/apis/shipstation-v1/docs/guides/errors","default":false,"active":false,"folderId":"58c9a61d"}],"sharedDataIds":{"sidebar":"sidebar-apis/@shipengine/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Error Handling","keywords":"shipping, labels, shipstation, documentation, api","siteUrl":"https://docs.shipstation.com","lang":"en-US","llmstxt":{"hide":false,"title":"ShipStation API LLM Docs","description":"Find links and references to all markdown documentation for use with LLMs","excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"error-handling","__idx":0},"children":["Error Handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When errors occur, ShipStation API gives you the information you need to successfully handle the error and resolve the problem."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"http-status-codes","__idx":1},"children":["HTTP Status Codes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All HTTP responses include an ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/getting-started/rest#status-codes"},"children":["HTTP status code"]},", which signals whether the reqeusted operation was successful or not."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2xx","__idx":2},"children":["2XX"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the request was ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["entirely or partially successful"]},", then you'll get a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2XX"]}," status code, such as ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://httpstatuses.com/200"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200 OK"]}]},", ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://httpstatuses.com/201"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}]},", or ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://httpstatuses.com/204"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204 No Content"]}]},". You should still check ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#the-errors-array"},"children":["the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," array"]}," to determine whether any part of the request failed."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"4xx","__idx":3},"children":["4XX"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["4XX"]}," status code, such as ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://httpstatuses.com/400"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400 Bad Request"]}]},", ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://httpstatuses.com/404"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404 Not Found"]}]}," or ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://httpstatuses.com/409"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409 Conflict"]}]},", indicates that the API request was invalid in some way. These errors always mean you will need to change some part of the request before retrying it again. Perhaps there's a syntax error, or a required field is missing, or the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/guides/auth#api-keys"},"children":["API key"]}," is invalid. Check ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#the-errors-array"},"children":["the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," array"]}," to see exactly what's wrong."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"5xx","__idx":4},"children":["5XX"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If an error occurs on ShipStation API's servers or on a third-party server such as a carrier or marketplace, then you'll get a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5XX"]}," response. Examples include ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://httpstatuses.com/500"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500 Internal Server Error"]}]}," and ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://httpstatuses.com/503"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["503 Service Unavailable"]}]},". These errors usually aren't due to anything wrong with your API request. It's most likely a server-side problem."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-errors-array","__idx":5},"children":["The Errors Array"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["JSON responses include an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," field, which is an array of any errors that occurred. If the operation was entirely successful then the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," array will be empty. But if part or all of the operation failed, then the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," array will contain one or more ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#error-structure"},"children":["error objects"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here's an example of a response with errors. Notice that there are two error objects in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," array."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"request_id\": \"5a8d3073-2626-4a64-983d-29c5d55dce5e\",\n  \"errors\": [\n    {\n      \"error_source\": \"shipengine\",\n      \"error_type\": \"business_rules\",\n      \"error_code\": \"unspecified\",\n      \"message\": \"carrier_id se-12345 not found\",\n      \"field_name\": \"carrier_id\",\n      \"field_value\": \"se-12345\"\n    },\n    {\n      \"error_source\": \"shipengine\",\n      \"error_type\": \"validation\",\n      \"error_code\": \"invalid_field_value\",\n      \"message\": \"Invalid service_code\",\n      \"field_name\": \"service_code\",\n      \"field_value\": \"carrier_pigeon\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"request-id","__idx":6},"children":["Request ID"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As you can see in the example above, the response also includes a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["request_id"]}," field. This is a unique ID that we assign to all API calls. If you ever need to ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://help.shipengine.com/hc/en-us/requests/new"},"children":["contact us for support"]},", you can reference the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["request_id"]}," of the API call in question. This will allow our support team to quickly find the problem and assist you in resolving it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"error-structure","__idx":7},"children":["Error Structure"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each error object inside the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," array has the following structure:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Property Name"},"children":["Property Name"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_source"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The type of error. This can be used to handle all errors of a certain type the same way."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A code that indicates the specific error that occurred."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A description of the error. This is useful for logging or debugging, but you should ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," code against this field as messages can change over time."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["error-specific fields"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," or absent."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See our ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/reference/errors-codes"},"children":["Error Codes page"]}," for a complete list of the possible values for each of these fields."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here's an example of an error object. Notice that it has all of the error fields, plus some error-specific fields like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["confirmation"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carrier_id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carrier_code"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carrier_name"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"error_source\": \"shipengine\",\n  \"error_type\": \"business_rules\",\n  \"error_code\": \"confirmation_not_supported\",\n  \"message\": \"Adult signature confirmation is not supported by Australia Post.\",\n  \"confirmation\": \"adult_signature\",\n  \"carrier_id\": \"se-123456\",\n  \"carrier_code\": \"australia_post\",\n  \"carrier_name\": \"Australia Post\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"cors-errors","__idx":8},"children":["CORS Errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["ShipStation API does not support ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS"},"children":["CORS (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["C"]},"ross ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["O"]},"rigin ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["R"]},"esource ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["S"]},"haring)"]},". If you are using ShipEngine from a web app or mobile app, please review our ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/guides/auth#client-side-apps--cors"},"children":["authentication guidelines"]}," for client applications."]}]},"headings":[{"value":"Error Handling","id":"error-handling","depth":1},{"value":"HTTP Status Codes","id":"http-status-codes","depth":2},{"value":"2XX","id":"2xx","depth":3},{"value":"4XX","id":"4xx","depth":3},{"value":"5XX","id":"5xx","depth":3},{"value":"The Errors Array","id":"the-errors-array","depth":2},{"value":"Request ID","id":"request-id","depth":3},{"value":"Error Structure","id":"error-structure","depth":3},{"value":"CORS Errors","id":"cors-errors","depth":2}],"frontmatter":{"seo":{"title":"Error Handling"}},"lastModified":"2026-04-08T10:47:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/apis/shipengine/docs/guides/errors","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}