Errors

Every response includes a status of either success or error. When an error occurs, the message field describes what went wrong.

{
  "status": "error",
  "message": "Order 736745 Not Found",
  "execution_time": "0.0208 seconds"
}

Status Codes

Code	Meaning	What To Do
200	Success	No action required
201	Created	Returned when creating an order or an order history item
400	The request was rejected	Correct the request. The message field names the problem
401	Authentication failed	Check both required headers. See the note below
403	Refused	A rate limit or a per-order limit was reached
404	Not found	Check the ID and the path
405	The method is not accepted at this path	Check the method against the operation
413	The payload is too large	Reduce item metadata or variations. See the limits below
426	This account cannot use the API	Upgrade the account. See the note below
429	Rate limit exceeded	Wait for X-Retry-After seconds. See Rate Limits

Common Messages

Message	Code	Cause
Required Header Missing: ORDERDESK-STORE-ID	401	The Store ID header was not sent
Required Header Missing: ORDERDESK-API-KEY	401	The API key header was not sent
Invalid Store ID	401	No store exists with that ID
Invalid API Key	401	The key does not match that store
No Content Sent	400	The request required a body and none was sent
Invalid JSON Detected	400	The body was not valid JSON
No Order Items	400	An order was submitted without any order_items
Invalid Folder ID.	400	The folder does not belong to this store
Invalid order_by value of X	400	order_by was not a sortable order field
Order History Count Exceeded	403	The order already holds 250 history entries
Item Variation or Metadata Data Exceeds Limit.	413	See the size limits below
Invalid Route	404	The path does not exist
Invalid Method	405	That path does not accept this method

Size Limits

Exceeding any of these limits returns a 413 response.

Field	Limit when JSON-encoded
Order item metadata	15,000 characters
Order item variation_list	5,000 characters
Order checkout_data	3,500 characters
Order order_metadata	2,000 characters
An order note, including its date and username	2,000 characters

Duplicate Orders

If an order is recognized as a duplicate of one already in your store, the 400 response includes the ID of the existing order.

{
  "status": "error",
  "message": "Duplicate Order",
  "existing_order_id": "925086"
}

This ID can be used to update the existing order instead of searching for it.