About our API response codes

In order to simplify integration, we have tried to standardize the response codes that we return across our APIs. While not every API will necessarily return every response code, every API will adhere to the same meanings for the same response codes and – for errors – the same response formatting and semantic content.

Success

In the case of success, you will need to see the documentation for each API to see details on how the response is formatted and what API-specific data each contains. A delivery date response is very different than a carrier selection response, for instance. You can find a list of our APIs with a brief description of what they do in Shipium's APIs.

All successes will have the same response codes.

Success responses

Client and server error responses

In the case of failures from any Shipium API, you will always get one of the following return codes for the cases described, though not every API necessarily returns all of the return codes based on its operation. Likewise, every error will return data in the same format, though additional data may also be passed for certain error cases.

Error responses

Error responses fall into two groups based on the nature of the issue:

• 4XX. Client errors. Something in the nature of the request that was made prevents it from being completed. Examples include bad or missing data or lack of access to the data requested. These should generally be fixable by the caller.
• 5XX. Server errors. Something has gone wrong on the Shipium side of things, preventing us from responding to the request. Waiting and trying again may be successful, but the underlying reason does not appear to be related to details of the request made.

Common error messages

This section documents frequently encountered error messages, their causes, and how to resolve them.

Configuration errors

Fulfillment context not found

Error message.Found 0 fulfillmentContextDetail matches of type customer for [parameters]

HTTP status. 400 Bad Request

Cause. No fulfillment context configuration exists for the combination of origin location, fulfillment type, and account settings specified in your request. The system requires exactly one matching configuration.

Note: The term fulfillmentContextDetail in this error message refers to your fulfillment context configuration in the Shipium Console. The [parameters] portion reflects the values you provided in your API request (such as origin postal code, country, and fulfillment type).

Resolution.

• Verify a fulfillment context exists in the Shipium Console for your origin postal code and country.
• Confirm the fulfillmentType in your request matches your Console configuration.
• Check that any tags or third-party billing account references in your request match your configuration exactly.
• If using multiple fulfillment centers, ensure each has its own configuration for the relevant fulfillment type.

Multiple fulfillment context matches

Error message.Found 2 fulfillmentContextDetail matches of type customer for [parameters]

HTTP status. 400 Bad Request

Cause. Multiple fulfillment context configurations match your request parameters. The system requires exactly one match to determine shipping rules.

Note: This error indicates your Console has overlapping configurations. The [parameters] portion shows which request values matched multiple configurations.

Resolution.

• Review your fulfillment context configurations in the Shipium Console.
• Ensure each origin postal code has only one configuration per fulfillment type.
• Use more specific criteria (such as tags or third-party billing references) to differentiate between configurations.
• If you intentionally have multiple configurations for the same origin, ensure your API requests include enough detail to uniquely identify the correct one.

Tenant not found

Error message.Tenant specified by [tenantId] does not exist

HTTP status. 404 Not Found

Cause. The tenant identifier in your request does not match any configured tenant in the Shipium system.

Resolution.

• Verify the tenantId value matches your Shipium account configuration exactly (check for typos or extra whitespace).
• Confirm you are calling the correct environment (sandbox vs. production).
• Contact Shipium Support if you believe the tenant should exist but is not being recognized.

Carrier selection errors

No carrier available

Error message.Could not find a carrier to fulfill the request

HTTP status. 400 Bad Request

Cause. No carrier service method is available for the shipment based on the combination of origin, destination, package specifications, and delivery requirements.

Resolution.

• Check carrier contracts. Verify carrier contracts are configured for the origin-destination lane in the Shipium Console.
• Review package specifications. Confirm package dimensions and weight are within carrier limits for your configured services.
• Verify delivery date. Ensure the requested delivery date is achievable given current carrier transit times from your origin.
• Check carrier selection rules. Review any carrier selection rules that may be excluding carriers for this shipment type.
• Use evaluatedServiceMethods. Include includeEvaluatedServiceMethodIds: true in your request to see which carriers were considered and why they were excluded (see below and Evaluated Service Methods).

Understanding carrier exclusion reasons

When you include includeEvaluatedServiceMethodIds: true in your request, the response includes an evaluatedServiceMethods array showing why each carrier service was considered or rejected. This is your primary troubleshooting tool for carrier selection issues. You can find additional information in Evaluated Service Methods.

About SHIP_DATE_IN_PAST: This error commonly occurs when a request is submitted late in the day after the carrier's pickup cutoff time has passed. Each carrier has specific cutoff times (often early-to-mid afternoon) after which shipments are scheduled for the next business day. If your desiredDeliveryDate cannot be met with a next-day ship date, the carrier is excluded. Consider submitting requests earlier in the day or adjusting your delivery expectations for late-day orders.

Transient errors: Errors marked as Transient indicate temporary issues that are likely to resolve on retry. Your integration should implement retry logic with exponential backoff (for example: wait 1 second, then 2 seconds, then 4 seconds between attempts). If transient errors persist after 3-5 retries, contact Shipium Support.

Date and time errors

Delivery date in past

Error message.desiredDeliveryDate is too far in the past

HTTP status. 400 Bad Request

Cause. The desiredDeliveryDate specified in the request is a past date that cannot be fulfilled.

Resolution.

• Update desiredDeliveryDate to a future date ( Desired, Exact, & Guaranteed Delivery Dates)
• Alternatively, use businessDaysOfTransit instead of specifying an exact date ( Business Days of Transit).
• Verify your system clock is synchronized correctly if dates appear unexpectedly invalid.
• If you are in a timezone ahead of UTC, ensure your date formatting accounts for timezone differences.

Address validation errors

Invalid address

Error message.Unable to validate address

HTTP status. 400 Bad Request

Cause. The destination or origin address could not be validated against postal databases.

Resolution.

• Verify street address, city, state, and postal code are correct and consistent with each other.
• Use the Address Validation API to pre-validate addresses before creating shipments.
• Check for typos, abbreviation inconsistencies, or formatting issues.
• For international addresses, ensure the country code is correct (2-letter ISO 3166-1 format).

Common address formatting issues:

Invalid location

Error message.Invalid [address type] location at country [code] and postal [code]

HTTP status. 400 Bad Request

Cause. The postal code is not valid for the specified country, or the combination does not exist in postal databases.

Resolution.

• Verify the postal code format matches the country's requirements.
• Confirm the postal code exists and is currently in use (some codes are retired or reassigned).
• For US addresses, ensure the ZIP code matches the city and state provided.
• For newer developments or addresses, the postal database may not yet include them — contact Support if you believe the address is valid.

Carrier-specific errors

When Shipium communicates with carrier APIs, some error messages are passed through from the carrier. This section documents common carrier-specific errors and their resolutions.

UPS errors

UPS error codes typically appear in the format [code] -> [message]. The following are common UPS errors you may encounter:

Note: Some UPS error codes indicate configuration issues that require Shipium Support assistance. If you encounter an error code not listed above, contact Support with the full error message and shipment details.

DHL errors

DHL errors often relate to address field length requirements or communication issues.

Address field length errors

Error pattern.[field]: expected maxLength: [limit], actual: [length]

Cause. DHL has strict field length requirements. Address fields exceeding these limits are rejected.

Resolution. Ensure address fields meet DHL's maximum length requirements:

If your data exceeds these limits, abbreviate where possible or split long values across multiple address lines.

DHL communication errors

Error pattern.Error getting label or similar communication error

Cause. The DHL API returned an unexpected response. This is typically a transient issue.

Resolution.

• Retry the request (this is a transient error).
• If the error persists after 3-5 retries, contact Shipium Support with the shipment ID for investigation.

FedEx SmartPost errors

FedEx SmartPost shipments have specific restrictions. You may see a note in error messages stating: NOTE:"USPS_DELIVERY_CONFIRMATION" was added to the smart post special services — this is expected behavior, as delivery confirmation is automatically included with SmartPost shipments.

Validation error patterns

Validation errors follow consistent patterns. Understanding these general patterns helps you quickly identify and fix request issues.

Error response format

All API error responses follow a consistent structure:

{
  "timestamp": "2026-01-15T12:00:00.000Z",
  "status": XXX,
  "error": "XXX STANDARD_HTTP_LABEL",
  "message": "Useful information",
  "path": "/api/v1/path/that/was/called"
}

Response fields

Validation error responses

For validation errors (400 Bad Request), the response may include an additional errors array with details about each validation failure:

{
  "timestamp": "2026-01-15T12:00:00.000Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Validation failed",
  "path": "/api/v1/deliveryexperience/carrierselection/shipment",
  "errors": [
    {
      "code": "NotNull",
      "field": "shipTo.address.postalCode",
      "message": "must not be blank"
    }
  ]
}

4xx vs 5xx responses

Troubleshooting tips

General best practices

1. Enable verbose responses. Use includeEvaluatedServiceMethodIds: true to see carrier selection details and understand why carriers were excluded.
2. Validate addresses first. Use the Address Validation API before attempting to create shipments to catch address issues early.
3. Check the Shipium Console. Many errors relate to configuration; verify your fulfillment contexts, carrier contracts, and selection rules match your API requests.
4. Review recent changes. If errors appear suddenly, check for recent changes to carrier contracts, fulfillment contexts, or selection rules in the Console.
5. Implement retry logic. For transient errors (TIMEOUT, SERVER_ERROR), implement exponential backoff in your integration.

When to contact Support

Contact Shipium Support when:

• You receive persistent 5xx errors after multiple retries.
• Error messages reference codes or issues not documented here.
• You need help interpreting evaluatedServiceMethods exclusion reasons.
• Carrier communication errors persist across multiple attempts.
• You believe an address is valid but validation fails.

Information to include in Support requests

To help us resolve your issue quickly, include the following information (with sensitive data redacted):

Always include:

• The full error response (JSON)
• The shipment ID (if available)
• Timestamp of when the error occurred
• The API endpoint you called

Redact before sending:

• Personal information. Recipient names, phone numbers, email addresses
• Full addresses. Use partial info like city/state/ZIP only.
• API keys and tokens. Never include authentication credentials.
• Order IDs or customer IDs. Replace with [REDACTED] if not needed for debugging.

Example redacted request:

{
  "shipTo": {
    "address": {
      "addressLine1": "[REDACTED]",
      "city": "Seattle",
      "state": "WA",
      "postalCode": "98101",
      "countryCode": "US"
    },
    "contactInfo": {
      "name": "[REDACTED]",
      "phone": "[REDACTED]"
    }
  }
}

Resources

Your Shipium team member is available to help along the way. However, you might find these resources helpful:

• Terms and Definitions

• Troubleshooting Guide

• Contact Shipium Support

Updated 6 months ago