Error and status codes

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

The following table describes the codes used:

HTTP Code	Reason	Description
200	Success	The request was successful. The response contains the requested resource or the result of a requested action.
400	Bad request	The request was unacceptable. Ensure that all the required parameters are present and the syntax is correct, and then retry the request.
401	Unauthorized	The server refused the request. Ensure that the access token is valid, and then retry the request.
403	Forbidden	The request was denied. Ensure that you have permission to access this resource before retrying the request.
404	Not found	The resource couldn't be found. Ensure that the resource ID is correct or the identified issue is fixed, and then retry the request.
408	Request timeout	The server closed the connection which had become idle.
429	Too many requests	The 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.
500	Internal server error	An issue occurred on the Instacart servers. Retry the request later.
503	Service unavailable	The 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 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 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 code	Description
1001	Invalid parameter. The meta: key identifies the parameter.
2003	Retry later.
4000	Record not found.
4001	Invalid request.
4002	Failed to resolve a valid context.
500x	Internal issues.
9999	Multiple errors found. The errors array contains the errors.