API Errors
- 03 Jun 2024
- 4 Minutes to read
- Contributors
- Print
- DarkLight
API Errors
- Updated on 03 Jun 2024
- 4 Minutes to read
- Contributors
- Print
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
The following details possible errors that may be returned for an API request.
Overview
Errors that are not API-specific are listed first. Within each section, errors are organized by API structure.
ErrorMessage values are bolded. [Brackets] used in the ErrorMessage are equal to the value passed for the related element. An example is provided when an ErrorMessage is variable.
Error Response Structure
Example response for an API request where one or more errors were found:
General Errors
General ErrorMessages that may be returned for more than one type of API request.
| Related Element(s) | ErrorMessage | Details/Action |
|---|---|---|
| General Errors | ||
| User, API | User [username] does not have permissions to this API | |
| N/A | Unable to parse characters | Ensure that special characters are properly encoded and an encoding flag is included in your XML header. Example: <?xml version=""1.0"" encoding=""UTF-8""?> Example: <?xml version=""1.0"" encoding=""ISO-8859-1""?> |
| <Login> Errors | ||
| Login | Required element Login not found | Provide login credentials and verify the XML can be parsed |
| User, ClientID | User [username] does not have permissions to client: [clientID] | |
| Unable to determine desired client for this user | If user has access to more than one client, the ClientID is required | |
| Username, password | The username/password combination provided is invalid | |
| The username/password combination provided is disabled | ||
| Missing Element Errors | ||
| Varies by API | Format: Required element [Missing Element] not found Example: Required element Reference not found | See documentation for related API request for what fields are required |
| Address Errors | ||
| Name, Address1, City, State, PostalCode, Country | Format: Invalid address field: [invalid field] Example: Invalid address field: name | State: For Australia, Canada, Chile and US, please use 2-digit ISO code for the State value. For Hungary and Singapore, remove State value PostalCode: Confirm value is in the correct format for the destination country Country: Use 2-digit ISO country code |
| City, State, PostalCode | Example: Possible resolutions - Suggested Cities: EDMONDS, WOODWAY; Suggested Postal Codes: 6056, 98004, 98005, 98006 | If an address is invalid, possible resolutions are returned, including states, cities and/or postal codes. |
| City, State, Postal Code do not match | Address validation could not make a suggestion. Confirm city, state and postal code values | |
ImportRequest
Additional errors that pertain specifically to the ImportRequest.
| Related Element(s) | ErrorMessage | Details/Action |
|---|---|---|
| Misc. Errors | ||
| Reference | Invalid customer reference number | Reference numbers should be alphanumeric and 50 characters or less |
| ShipMethod | The client does not have access to the requested shipping service: [ShipMethod] | Confirm ShipMethod values with Integration Manager |
| Invalid shipping service requested: [ShipMethod] | ||
| ItemsCurrency | Unsupported or invalid currency [ItemsCurrency] passed. Currencies expected using a three character, ISO 4217 code. | |
| Label Errors | ||
| LabelFormat | Example: Invalid label format [LabelFormat] requested. Support image types are pdf, jpg, gif, png, bmp, zpl. | Supported image types may change. See related API documentation for the current list of supported image formats |
| LabelEncoding | Invalid label encoding '[LabelEncoding]'. With LabelFormat ZPL, must use label format ZPL or omit the tag. | |
| <VendorInformation> Errors | ||
| VendorName, VendorAddress1, VendorCity, VendorCountry | Example: No vendor name specified for [Reference], required if providing third party logistics | "Error is returned if one of these elements is included but the others are blank VendorInformation is required for 3PLs (third-party logistics) |
| <Items> Errors | ||
| Items | This shipment has no items. One or more is required to process. | At least one item is required for all orders |
| Sku, Quantity, UnitPrice, Description, CountryOfOrigin | Example: Required element Sku not found in Item element 1 | Returned when missing element is required. Error will reference missing element and item element number |
| Example: Invalid quantity provided for sku 1. in Item element 1 | Error will reference invalid element and item element number Sku: Max length is 64 characters. Use a unique, alphanumeric value and remove special characters other than: - _ Quantity: Requires integer value UnitPrice: Use real item value Description: Max length is 255 characters CountryOfOrigin: Use 2-digit ISO country code | |
Other Errors
ErrorMessages that pertain specifically to other available API methods.
| Related Element(s) | ErrorMessage | Details/Action |
|---|---|---|
| TrackRequest | ||
| Reference | Either Reference, Package Reference or TrackingNumber is required, none were found. | |
| InventoryLevelRequest | ||
| ClientID, Facility | No Landmark facilities are set up to handle fulfillment for 'client name' | |
| Facility | Unknown facility [Facility] | Confirm facility with Integration Manager. Can pass by ID, Name or ShortName |
| Facility: [Facility] is not set up to support inventory for 'client name' | ||
| Sku | Unknown sku: [Sku] | |
| PreClearanceRequest | ||
| MAWB | MAWB required | |
| OriginAirport | OriginAirport required | Use 3-digit airport codes |
| Shipments | No shipments were specified | At least 1 shipment must be specified |
| Reference | Format: Shipment [Reference] already in 'precelarance_id' Example: Shipment 17 already in PC23 | Returned when a shipment has already been precleared |
| Shipment with reference [Reference] not found | Value should be the same Reference field passed in the ImportRequest | |
| Could not find appropriate broker. Please contact Landmark IT. | ||
| N/A | Format: Failed sending pre-clearance: 'detail message' Example: Unknown preclearance ID | Contact Integration Manager |
Rate limits and throttling
All endpoints have maximum request limits implemented in order to prevent abuse and ensure API availability for all users. Limitations are implemented at two different levels as shown below
Application-level throttling
Requests from a single API user: 300 per 1 minute, per endpoint. Errors are sent back in response to the request just as normal. If you are being throttled, you will see:
- HTTP response code: 200 (although a 200 response code normally indicates a success, if throttling has occurred the "Success" element will be "false")
- Error code: "rate_limit"
- Error message: "Rate limit is exceeded. Retry after X seconds".
Time Frame
Hits are counted per actual minute (i.e. from 10:02:01.00 to 10:03:00.99). So the counter is reset at the first second of each new minute - you can see this in api_rate.expires_at, but also we put the number of seconds until the new minute in the error message.
As an example, for a ShipRequest, the response would look like:
<ShipResponse>
<Result>
<Success>false</Success>
<ResultMessage>See Errors element for error details</ResultMessage>
</Result>
<Errors>
<Error>
<ErrorCode>rate_limit</ErrorCode>
<ErrorMessage>Rate limit is exceeded. Retry after 6 seconds</ErrorMessage>
</Error>
</Errors>
</ShipResponse>
Server-level throttling
Requests from a single IP address are limited to 3000 per rolling 5 minute period. If you are being throttled, you will see:
- HTTP response code: 429
- Response message: "Too Many Requests"
- Response message body: "You have exceed the rate limit. Please try again later."
Was this article helpful?