Skip to main content

Error and status codes

For all responses, Instacart Connect returns a standard HTTP status code.

The following table describes the codes used by Instacart Connect:

HTTP CodeReasonDescription
200SuccessThe request was successful. The response contains the requested resource or the result of a requested action.
400Bad requestThe request was unacceptable. Ensure that all the required parameters are present and the syntax is correct, and then retry the request.
401UnauthorizedThe server refused the request. Ensure that the access token is valid, and then retry the request.
403ForbiddenThe request was denied. Ensure that you have permission to access this resource before retrying the request.
404Not foundThe resource couldn't be found. Ensure that the resource ID is correct or the identified issue is fixed, and then retry the request.
408Request timeoutThe server closed the connection which had become idle.
429Too many requestsThe number of your requests has exceeded the rate limit for requests per second. Retry the request later. If you receive this error repeatedly, contact your Instacart representative.
500Internal server errorAn issue occurred on the Instacart servers. Retry the request later.
503Service unavailableThe server couldn’t fulfill the request, possibly due to being overloaded or temporarily down for maintenance. Retry the request later.

200 responses

When you get, create, or update a resource such as an order, the response contains the data associated with the resource. For details about the responses, see the Response section in each endpoint topic.

4xx client-side errors

In general, 4xx errors require a corrective action. Identify and fix the reported issue before you send an updated request.

Instacart Connect has two standard response formats for errors: single error response format and multiple errors response format. For specific details about the possible errors associated with each endpoint, see the Response section in each endpoint topic.

Single error response format

Single error responses have a format similar to the following example:

{
"error": {
"message": "User not found",
"code": 1001
},
"meta": {
"key": "user_id"
}
}

where

  • error: message describes the cause of the error.
  • error: code is an internal error code identifier.
  • meta contains the parameters that are associated with the error, if any.
  • meta: key identifies a parameter.

Generally speaking, you can identify errors through a combination of the error: code and the meta: key. For example, an error: code of 1001 means that a parameter is invalid and the key: user_id identifies that the problem is with the value of the user ID.

Multiple errors response format

A response that contains multiple errors has a format similar to the following example:

{
"error": {
"message": "There were issues with your request",
"code": 9999,
"errors": [
{
"error": {
"message": "can't be blank",
"code": 1001
},
"meta": {
"key": "order.service_option_id"
}
},
{
"error": {
"message": "can't be blank",
"code": 1001
},
"meta": {
"key": "order.address_id"
}
},
{
"error": {
"message": "can't be blank",
"code": 1001
},
"meta": {
"key": "items[0].count"
}
}
]
},
"meta": {}
}

where

  • error: message indicates there are multiple errors.
  • error: code is an internal error code for the set of errors.
  • error: errors is an array of errors in the same format as the single error responses.
  • meta might contain other parameters related to the set of errors.

The multiple errors format always has an error: code of 9999.

5xx server-side errors

The Operations team actively monitors and resolves internal server issues. You can retry requests that resulted in 5xx errors. If the problem persists, contact your Instacart representative.

An exponential backoff strategy is recommended for retries. Before you implement a retry strategy, discuss your plan with your Instacart Connect representative.

Server-side error responses have a format similar to the following example:

{
"error": {
"message": "Sorry, an unexpected error occurred. Our team has been notified. Please try again later.",
"code": 5000
},
"meta": {}
}

where

  • error: message describes the cause of the error.
  • error: code is an internal error code identifier.
  • meta is empty for server-side issues.

Error codes

The following table defines some of the error codes you might see:

Error codeDescription
1001Invalid parameter. The meta: key identifies the parameter.
2003Retry later.
4000Record not found.
4001Invalid request.
4002Failed to resolve a valid context.
500xInternal issues.
9999Multiple errors found. The errors array contains the errors.