Order API v2 error codes and troubleshooting
Reference guide for common Order API v2 error codes, response format, and troubleshooting steps.
Table of Contents
- Troubleshooting by error code
- OS0001 - Unexpected internal error
- OS0002 - Service call failed
- OS0003 - Invalid request
- OS0004 - Order processing error
- OS0005 - Forbidden
- OS0006 - Authentication required
- OS0007 - Temporary platform issue
- Common troubleshooting scenarios
- Temporary platform issue
- Unsupported parcel type for country
- Missing required query parameter
- Invalid sales order identifier
- Missing or invalid credentials
Error Code Overview
| Error Code | Type | Meaning | Client Action |
|---|---|---|---|
| OS0001 | INTERNAL_SERVER_ERROR | The request could not be completed due to an unexpected internal issue. | Retry later. If it persists, contact support. |
| OS0002 | CROSS_SERVICE_ERROR | A required service call failed while processing the request. | Retry later. If the issue persists, contact support. |
| OS0003 | VALIDATION_ERROR | The request is invalid, incomplete, or contains unsupported values. | Correct the request and retry. |
| OS0004 | CROSS_SERVICE_ERROR | The order could not be processed due to an order processing dependency. | Retry later. If the issue persists, contact support with order details. |
| OS0005 | AUTHENTICATION_ERROR | The request is authenticated, but access to the requested resource is not allowed. | Verify that your client has access to the requested resource. |
| OS0006 | AUTHENTICATION_ERROR | Authentication is missing, invalid, or expired. | Log in again or refresh the session, then retry with valid credentials. |
| OS0007 | INTERNAL_SERVER_ERROR | The request could not be completed because a temporary platform issue occurred. | Retry later. If it persists, contact support. |
Unsupported parcel type for country
Error code: OS0003
Type: VALIDATION_ERROR
What it means
The request could not be processed because the parcel type provided in the request is not supported for the selected country.
This is a validation error that can be corrected by updating the request payload.
When this can happen
This error can occur when creating a sales order if the submitted parcel type is not available for the country used in the order address or selected flow.
What to check
Verify that the parcel type used in the request is supported for the provided country.
Also check that the country, parcel type, address details and flow-specific configuration are correct for the order you are trying to create.
How to fix it
Update the request with a supported parcel type for the provided country, then retry the request.
If you are not sure which parcel types are supported for your setup, contact support with the request timestamp, endpoint, and order reference.
Example message
Invalid request: the parcel type is not supported for the provided country.Missing required query parameter
Error code: OS0003
Type: VALIDATION_ERROR
What it means
The request could not be processed because a required query parameter is missing.
For example, when retrieving a sales order list, the clientOrderId query parameter is required.
What to check
Verify that all required query parameters are included in the request and that their values are not empty.
How to resolve
Add the required clientOrderId query parameter, provide a valid value, and retry the request.
Example message
Invalid request: clientOrderId is required as a query parameter.Invalid sales order identifier
Error code: OS0003
Type: VALIDATION_ERROR
What it means
The request could not be processed because the provided sales order identifier is invalid.
This can happen when the salesOrderId path parameter does not match a valid existing sales order.
What to check
Verify that the salesOrderId used in the request path is correct and refers to an existing sales order.
Also check that the identifier was copied correctly and was not truncated, modified, or taken from a different environment.
How to resolve
Update the request with a valid existing salesOrderId, then retry the request.
Example message
Invalid request: the provided salesOrderId is invalid.Invalid or missing credentials
Error code: OS0006
Type: AUTHENTICATION_ERROR
What it means
The request could not be processed because authentication is missing, invalid, or expired.
What to check
Verify that the request includes a valid authentication token or credentials. Also check that the session has not expired and that the credentials are being sent in the expected authorization header.
How to resolve
Log in again or refresh the session, then retry the request with valid credentials.
If the issue persists, verify the authentication setup used by your integration or contact support.
Example message
Authentication required: your session has expired or your credentials are not valid.Temporary platform issue
Error code: OS0007
Type: INTERNAL_SERVER_ERROR
What it means
The request could not be completed because a temporary platform issue occurred while processing the request.
This is usually not caused by invalid request data.
What to check
Check whether the same request succeeds after a short delay.
Also verify that the endpoint, order reference, and request payload are correct before retrying.
How to resolve
Retry the request after a few moments.
If the issue persists, contact support with the request timestamp, endpoint, and order reference.
Example message
Something went wrong: we're unable to process your request at the moment. Please try again later.