ApiError

Object

The ApiError object contains detailed error information returned by the API when a request fails. This object is part of the error response envelope and provides structured information about what went wrong.

Fields

Field	Type	Description
`code`	string	A specific error code that identifies the type of error. This can be used for programmatic error handling. Common values include: "unauthorized", "bad_request", "not_found", "rate_limited", and "internal_error". See the Error codes documentation for a complete list.
`message`	string	A human-readable error message that describes what went wrong. This message is suitable for displaying to end users or for logging purposes.
`details`	object	An object containing additional context-specific error information. The structure of this object varies depending on the error type. It may be empty ({}) or contain fields such as field, reason, resource, id, retryAfter, etc. See the details examples below.

Note

The ApiError object is always present in error responses (when success is false) and is null in successful responses.

The details object structure is dynamic and depends on the error type. Some errors may include validation information, resource identifiers, or retry instructions.

This object is returned as part of error responses from all API endpoints. See the Error codes documentation for a complete reference of error codes, HTTP status codes, and error handling guidance.

Details object examples

The details object structure varies by error type. Here are common examples:

Bad Request (400)

Validation errors typically include information about which field failed and why:

{
  "code": "bad_request",
  "message": "Invalid product ID format",
  "details": {
    "field": "productId",
    "reason": "Expected a valid Shopify product REST ID"
  }
}

Not Found (404)

Resource not found errors include information about what resource was missing:

{
  "code": "not_found",
  "message": "Product not found",
  "details": {
    "resource": "product",
    "id": "123"
  }
}

Rate Limited (429)

Rate limit errors may include retry information:

{
  "code": "rate_limited",
  "message": "Too Many Requests",
  "details": {
    "retryAfter": 60
  }
}

Unauthorized (401) / Internal Error (500)

Some errors may have empty details objects:

{
  "code": "unauthorized",
  "message": "Unauthorized",
  "details": {}
}

Complete error response example

The ApiError object is part of the error response envelope:

{
  "success": false,
  "data": null,
  "error": {
    "code": "bad_request",
    "message": "Invalid product ID format",
    "details": {
      "field": "productId",
      "reason": "Expected a valid Shopify product REST ID"
    }
  },
  "meta": {},
  "requestId": "req_abc123"
}