Overview
This article catalogs the errors the ShipStation API v2 integration can record in iPaaS.com, grouped by flow. Each error starts with a stable code you can search for on this page, followed by the message, the condition that causes it, and how to resolve it. Errors appear in iPaaS.com under Dashboard / Integration Monitoring / Error Logs. When ShipStation refuses a call, the message includes ShipStation's own explanation and its request id, which ShipStation support can use to trace the call. When an order has several shipments, the error for each failed shipment is listed inside one SSV2-EXTN-1004 message, so search this page for every code that message contains.
iPaaS.com categorizes errors by families. You can learn more about that categorization at Understanding iPaaS.com API Error Codes.
Some resolutions refer to your Managed Integration Service Provider (MiSP): the partner who set up and manages your iPaaS.com integration, including its mappings, settings and credentials.
Supported Flows
Authentication and Connection
Any ShipStation Call
Order FROM iPaaS.com
LTL Freight (Order FROM iPaaS.com)
Shipment Tracking TO iPaaS.com
Error Collection
Authentication and Connection
The integration checks the connection at the start of each transfer. When the connection is refused, the transfer error reads Unable to connect to subscription with id {subscription id}, and the coded message below is recorded in the iPaaS.com logs at the same time.
API Key setting missing
Unable to find required Setting: API Key
Description: The subscription has no API Key setting at all. iPaaS.com stops before the integration can check the key, so this message has no SSV2 code.
Resolution: On the subscription settings page, enter the ShipStation API v2 key in API Key and save. Create the key in ShipStation under Settings → Account → API Settings.
API Key setting blank
SSV2-AUTH-1001 - The API Key setting is required. Make an API key in ShipStation under Settings → Account → API Settings (API v2).
Description: The API Key setting exists but is blank or contains only spaces. No call to ShipStation is made.
Resolution: Create an API v2 key in ShipStation under Settings → Account → API Settings, paste it into API Key on the subscription, and save.
API key rejected
SSV2-AUTH-1002 - ShipStation rejected the API Key: {details}. Check the key in ShipStation under Settings → Account → API Settings, and that it is an API v2 key.
Any later call ShipStation refuses with status 401 uses the same code: SSV2-AUTH-1002 - ShipStation refused {action} (401): {details}
Description: ShipStation did not accept the key. It is mistyped, was regenerated or deleted in ShipStation, or is a key from the older ShipStation API rather than API v2. The message never repeats the key.
Resolution: Copy the current API v2 key from ShipStation under Settings → Account → API Settings, paste it into API Key, and save.
API key not allowed
SSV2-AUTH-1003 - The API key works but isn't allowed to read warehouses: {details}. Check the ShipStation plan includes API v2.
Any later call ShipStation refuses with status 403 uses the same code: SSV2-AUTH-1003 - ShipStation refused {action} (403): {details}
Description: ShipStation accepted the key, but the ShipStation plan or user does not allow the call.
Resolution: Confirm in ShipStation that the account's plan includes API v2 access and the feature the call names, then resend the record.
API Url is not a web address
SSV2-AUTH-1004 - The API Url setting isn't a web address. Use https://api.shipstation.com/v2 (or leave it blank).
Description: The subscription's API Url setting is not a valid web address, so no call to ShipStation can be made.
Resolution: Set API Url to https://api.shipstation.com/v2, or clear it to use that default, and save.
Any ShipStation Call
ShipStation refused the data
SSV2-VALD-1001 - ShipStation refused {action} ({status}): {details}
Description: ShipStation returned status 400 or 422 because a value it was sent is missing or not allowed. The details name the field and ShipStation's reason, for example a currency that is not a currency code (amount_paid.currency: Requested value 'us dollars' was not found) or a weight unit ShipStation does not support.
Common causes and resolutions:
A value ShipStation does not allow: correct the value the details name in the source record or its mapping, then resend the record. Currencies must be three-letter ISO codes such as USD, and weights must use a unit ShipStation supports, such as pounds, ounces, grams or kilograms.
Carrier does not know the tracking number yet (Shipment Tracking TO iPaaS.com): the message reads ShipStation refused reading label tracking (400): A shipping carrier error occurred: Carrier returned error code: TRACKING.TRACKINGNUMBER.NOTFOUND. A label was created moments ago and the carrier has not registered its tracking number yet. Wait a few minutes, then retry the transfer from Dashboard / Integration Monitoring / Error Logs.
Resolution: Read ShipStation's reason in the details and act on the matching cause above.
Record not found
SSV2-NFND-1001 - ShipStation refused {action} (404): {details}
Description: The ShipStation record the call names no longer exists. It was deleted in ShipStation, or its id belongs to a different ShipStation account. Checks for a record that is expected to be missing do not raise this error.
Resolution: Look for the record in ShipStation. If it was deleted on purpose, no action is needed. If the subscription was pointed at a different ShipStation account, ask your MiSP to review the record's linked ids.
ShipStation refused the call
SSV2-EXTN-1001 - ShipStation refused {action} ({status}): {details}
At the start of a transfer the message reads SSV2-EXTN-1001 - ShipStation answered {status} while validating the connection: {details}
Description: ShipStation refused the call with a status not covered by the errors above. ShipStation's message is included.
Resolution: Correct what ShipStation's message names, then resend. If the cause is unclear, your MiSP can raise it with ShipStation support using the request id in the message.
ShipStation unavailable
SSV2-EXTN-1002 - ShipStation couldn't complete {action} right now ({reason}). Resend the record once ShipStation answers again.
At the start of a transfer the message reads SSV2-EXTN-1002 - Couldn't reach {API Url}: {reason}. Check the API Url setting.
Description: ShipStation answered with a server error, or did not answer at all. This is usually temporary.
Resolution: Resend the record once ShipStation is answering again. Check ShipStation's status page for an outage. If the connection message keeps appearing, check that API Url is https://api.shipstation.com/v2 or blank.
ShipStation rate limit reached
SSV2-RATE-1001 - ShipStation rate limit reached during {action}; retrying after {seconds}s.
Description: ShipStation limits how many requests an account can make in a set period, and that limit was reached.
Resolution: No action is needed: iPaaS.com holds the transfer until ShipStation's limit resets, then retries it. If this happens often, lower Concurrent Batch Executions on the subscription.
Order FROM iPaaS.com
Order has no Order Number
SSV2-VALD-1002 - The order has no Order Number. Map the transaction number to Order Number.
Description: The order reached the integration without an Order Number, which ShipStation requires. Nothing was sent.
Resolution: Map the transaction number to Order Number in the Order collection, then resend the transaction.
Order has nothing to ship
SSV2-VALD-1003 - Order {number} wasn't sent to ShipStation because {reason}.
Description: The reason is one of it has no addresses, it has no lines, or no line has a usable destination. With Enable Multi Address Shipment turned on, each line whose destination does not match an address on the order is also listed. Nothing was sent.
Resolution: Check that the transaction has a shipping address and lines, and that the Address and Line collections and their filters let them through. For multi-address orders, make sure each line's destination matches an address on the order. Then resend the transaction.
Some of the order's shipments failed
SSV2-EXTN-1004 - {n} problem(s) sending order {number} to ShipStation; {sent} of {total} shipment(s) are in ShipStation. Details: {each failure}
When the order is cancelled or deleted, the message reads SSV2-EXTN-1004 - Order {number}: not every shipment could be cancelled: {each failure} or SSV2-EXTN-1004 - Not every shipment of the order could be cancelled: {each failure}
Description: An order goes to ShipStation one shipment (destination) at a time. One or more shipments failed, and the message lists each one with its own error, which often carries its own SSV2 code. The other shipments were sent. A common cancel failure is a shipment that already has a label.
Resolution: Look up each code in the details on this page and fix what it names. Before you resend, check ShipStation for the shipments the message says were sent, so nothing is created twice by hand. For a shipment that already has a label, void the label in ShipStation, then cancel the order there.
Warehouse name not found
SSV2-VALD-1006 - No ShipStation warehouse is named "{name}" (ShipStation Ship From Location, {shipment number}). Use the name exactly as ShipStation shows it, or leave it blank to use the default warehouse.
Description: The order or one of its addresses names a ship-from warehouse in ShipStation Ship From Location that ShipStation does not have. Rather than ship from the default warehouse, the integration does not send that shipment. This error appears inside SSV2-EXTN-1004, and the order's other shipments are still sent.
Resolution: Change ShipStation Ship From Location to the warehouse name exactly as ShipStation shows it under Settings → Ship From Locations (capitalization does not matter), or clear it to use the default warehouse. Then resend the transaction.
ShipStation did not confirm the order
SSV2-EXTN-1003 - ShipStation didn't confirm the order {shipment number}: {detail}
Description: ShipStation accepted the order but returned no id, and the integration could not find the order in ShipStation afterward. This error appears inside SSV2-EXTN-1004.
Resolution: Search ShipStation for the order number. If the order is not there, resend the transaction. If it is there, ask your MiSP to link it before resending, so a duplicate is not created.
Collection type not supported
SSV2-VALD-1005 - Mapping collection type {type} isn't supported by this integration. It supports Transaction (with Address and Line) FROM iPaaS.com, and Transaction Tracking and Shipping Method TO iPaaS.com.
Description: The subscription has a mapping collection for a data type or direction this integration does not handle.
Resolution: Remove or deactivate that mapping collection. Use the template collections for the supported data types.
LTL Freight (Order FROM iPaaS.com)
Freight details incomplete
SSV2-VALD-1004 - Freight for {shipment number} can't be quoted: {each missing item}
For an unrecognized accessorial, the message reads: SSV2-VALD-1004 - Freight accessorial {name} isn't one ShipStation knows ({the accepted names}).
Description: An order with Freight Mode set to Quote or Book is missing freight data. Every freight line needs a Freight Class (50 to 500), a weight, and handling unit length, width and height in inches, and accessorials must use ShipStation's names. The message lists each missing or incorrect item.
Resolution: Fill in the items the message lists on the source order or in its mappings, then resend the transaction.
No freight provider account
SSV2-FRGT-1001 - No freight provider account: map Freight Provider Account on the order or set the Freight Provider Account setting (find it in ShipStation, or with GET /v2/freight/provider_accounts).
Description: The order asks for freight, but neither the order nor the subscription names a ShipStation freight provider account.
Resolution: Set the Freight Provider Account setting on the subscription, or map it on the order, to the id of a freight provider account connected in ShipStation. Your MiSP can look up the id if it is not shown in ShipStation. Then resend the transaction.
No LTL offers
SSV2-FRGT-1002 - No carrier offered an LTL quote for {shipment number}. Check the lane, freight classes and dimensions in ShipStation.
Description: ShipStation returned no freight offer that has not expired.
Resolution: Check the ship-from and ship-to addresses, freight classes, dimensions and accessorials, and that the freight provider account is active in ShipStation. Then resend the transaction.
Booking refused without its transaction
SSV2-FRGT-1003 - Freight for {shipment number} wasn't booked: without its iPaaS.com transaction the integration can't make sure it books only once. Book it in ShipStation instead.
Description: Booking freight dispatches a carrier, so with Freight Mode set to Book the integration records each booking on the order's iPaaS.com transaction. The order's link to its transaction was missing, so nothing was booked.
Resolution: Book this shipment's freight in ShipStation.
Freight may already be booked
SSV2-FRGT-1004 - Freight for {shipment number} may already be booked: an earlier booking started, but its result never reached iPaaS.com. Check ShipStation's freight shipments for this order before anything else. If it was booked, don't book again. If it wasn't, resend the order with Freight Mode Quote, then Book.
Description: Before it books, the integration marks the booking as started on the order. That mark is still there without a booking result: the booking may have gone through while recording it in iPaaS.com failed, or ShipStation did not answer. The integration will not risk dispatching a second carrier.
Resolution: Check the order's freight shipments in ShipStation. If it was booked, do not book again; record the booking on the order by hand, because the integration cannot link a booking it did not record. If it was not booked, resend the order with Freight Mode set to Quote (this clears the mark), then send it again with Book.
Freight setting can't be read at booking
SSV2-FRGT-1005 - Freight for {shipment number} wasn't booked: {each problem}
Each problem reads Freight Offer Selection is "{value}"; use Cheapest or Fastest. or Freight Pickup Window is "{value}"; use HH:mm-HH:mm, for example 09:00-17:00.
Description: With Freight Mode set to Book, a filled-in Freight Offer Selection or Freight Pickup Window that the integration cannot read stops the booking instead of falling back to the default. Nothing was booked.
Resolution: Correct the setting on the subscription, or clear it to use the default, then resend the transaction.
iPaaS.com refused a freight tracking record
SSV2-EXTN-1005 - iPaaS.com refused the freight tracking record for {shipment}: {iPaaS.com's reason}. If it names the shipping method (VALD-1036), run shipping_method/initialize first.
Description: The integration records each LTL quote and booking as tracking on the transaction, and iPaaS.com refused that record. The most common reason is that the LTL Freight (ShipStation) Shipping Method does not exist in iPaaS.com yet.
Resolution: Fix the reason iPaaS.com gives. For a shipping method reason, run the Shipping Method initialize transfer for the subscription, then resend the transaction. If this happened while a booking was being marked as started, nothing was booked; if it happened after the booking, the next send stops with SSV2-FRGT-1004 instead of booking again.
Shipment Tracking TO iPaaS.com
Tracking shipping method not found in iPaaS.com
iPaaS.com refuses the tracking record because its shipping method is not an existing Shipping Method.
Description: iPaaS.com requires each tracking record's shipping method to match the name of a Shipping Method that already exists in iPaaS.com. This is an iPaaS.com error without an SSV2 code. It appears when Shipping Methods have not been loaded yet, or when the Shipping Method collection's filter excludes the carrier service the label used.
Resolution: Run the Shipping Method initialize transfer after connecting carriers in ShipStation, and make sure the Shipping Method filter includes the carrier service. Then retry the tracking transfer.
Webhook address or key missing
SSV2-HOOK-1001 - iPaaS.com didn't supply this subscription's webhook address (IPaaSApi_WebhookUrl).
Or: SSV2-HOOK-1001 - iPaaS.com didn't supply this subscription's webhook key (WebhookApiKey).
Description: The integration could not register the tracking webhook in ShipStation because iPaaS.com did not supply the subscription's webhook address or key.
Resolution: Save the subscription again, then turn the track_event_v2 webhook off and on. If the error continues, ask your MiSP to review the subscription's webhook configuration.