Errors

The Archive API reports failures at three levels. You can tell which level failed from the HTTP status and the shape of the response body, so check those first.

Identifying the error level

1. HTTP status is not 200: transport error. Authentication, a missing header, or an unknown workspace fails before any of your query’s fields are resolved. The body is a single string under errors (429 is the exception; see the table below):

{ "errors": "<message>" }

{
  "errors": "WORKSPACE-ID header is required"
}

2. HTTP status is 200 but the body has an errors array: GraphQL error. The request was transported and parsed, but a field failed. Each entry carries a message, a machine-readable extensions.code, and locations / path pointing into your query:

{
  "errors": [
    {
      "message": "Preset \"00000000-0000-0000-0000-000000000000\" was not found in the current workspace.",
      "extensions": {
        "code": "WRONG_VIEW_TYPE_FOR_ITEMS",
        "allowedAccessors": [
          "media_deck",
          "collections"
        ]
      },
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "items"
      ]
    }
  ],
  "data": null
}

Match on extensions.code (WRONG_VIEW_TYPE_FOR_ITEMS in this example) rather than on the message text, which can change.

A response can carry both data and errors: when a dependency is temporarily unavailable, the parts that could be resolved are still returned alongside a coded error for the parts that could not. Read errors even when data is populated.

3. HTTP 200 with data and no errors: success. A mutation may still report a business failure, though. Every mutation payload has a userErrors array; an empty array means the write succeeded.

{
  "data": {
    "createCollection": {
      "collection": {
        "id": "17ccdf4e-19d2-5b30-9787-d4f0886ddf29",
        "name": "Holiday Favorites",
        "itemCount": 0
      },
      "userErrors": []
    }
  }
}

The userErrors pattern

Mutations don’t raise validation failures as GraphQL errors. They return them in userErrors, so the request still comes back HTTP 200 with data. Each UserError has the shape:

type UserError {
  field: [String!]
  message: String!
}

Always inspect userErrors on a mutation response before treating it as a success. field points at the offending input path; message is human-readable.

HTTP status reference

Server-side errors arrive as HTTP 200

A failure inside the server doesn’t usually change the status code. It comes back in the GraphQL error envelope, so match on extensions.code rather than waiting for a 5xx:

For the unknown-workspace case:

{
  "errors": "Shop not found"
}

See the Rate limits guide for 429 handling and the Authentication guide for 401 handling.