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. See 401 Unauthorized responses.
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.
423	Locked	The target resource is locked. The resource named by meta.key is temporarily locked by another operation. For example, this can occur when the same user account is being created concurrently. Wait briefly and retry the request. The lock clears automatically. If it persists, contact your Instacart representative.
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": "can't be blank",
    "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.

401 Unauthorized responses

A 401 response means the server refused the request. Common causes include a missing token, an expired token, or a token that does not match this data host, retailer slug, or country. If the cause is unclear, contact your Instacart representative.

Access tokens are valid for 24 hours from created_at. A request can return 401 before the token expires if it is used with the wrong host, retailer slug, or location code.

Symptom or message	What it usually means	What to do
Token older than 24 hours, or expires_in elapsed	The access token expired.	Generate a new token on the OAuth host Instacart assigned for your integration. See Authentication.
the given location code doesn't match the oauth token used.	location_code, X-Retailer-Id, and the OAuth token are not bound to the same banner and country.	Use the slug, location code, and token issued together. See Identifiers.
401 before 24 hours have passed, with a host or credential mismatch	The token is not valid for this data host, retailer slug, or country. Staging accepts a production token.	Mint a token on the host Instacart assigned for this integration and retry. For staging, see Environments and testing.

Do not retry the same request with the same token after a 401 unless you have rotated the token or corrected the header and location_code binding.

5xx server-side errors

The Operations team actively monitors and resolves internal server issues. You can retry idempotent requests that resulted in 5xx errors. Do not automatically retry Track ad events or other non-idempotent requests. 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.