Error Handling

GraphQL always returns HTTP 200 — even when something goes wrong. Always check the response body for errors.

The API uses two different error response shapes depending on the type of error:

Authentication and header errors return a string:


{
  "errors": "Missing or invalid authentication token"
}

GraphQL errors (invalid fields, type errors, etc.) return an array:


{
  "errors": [
    {
      "message": "Field 'x' doesn't exist on type 'Query'",
      "locations": [{ "line": 1, "column": 3 }],
      "extensions": { "code": "undefinedField" }
    }
  ]
}

Always handle both shapes in your code.

Query errors

Appear in the top-level errors array:


{
  "errors": [
    {
      "message": "Unauthorized",
      "extensions": { "code": "UNAUTHORIZED" }
    }
  ]
}

Common query errors and how to fix them

Error	Cause	Fix
`Missing or invalid authentication token`	Token is missing, expired, or incorrectly formatted	Check that your `Authorization` header is `Bearer <your_token>`. Make sure there are no extra spaces or quotes.
`Unauthorized`	Token is valid but doesn’t have permission for this operation	Confirm your token has access to the workspace you’re querying. Contact support@archive.com if you need permissions updated.
`Shop not found`	The `WORKSPACE-ID` header has an invalid UUID	Double-check the workspace UUID. Run the `workspaces` query (no WORKSPACE-ID needed) to get your valid IDs.
`first must be less than or equal to 100`	You requested more than 100 results per page	Set `first` to 100 or less. Use pagination (`after` cursor) to get more results.
`Cannot coerce ... to DateTime`	Date is not in UTC format	Dates must end with `Z` (e.g., `2026-03-01T00:00:00Z`), not just `2026-03-01`.
`Field '...' doesn't exist on type 'Query'`	You’re using a field name that doesn’t exist in the schema	Check the field name for typos. Refer to the documentation for valid field names.

Mutation errors

Appear in userErrors inside the mutation result:


{
  "data": {
    "addItemToCollections": {
      "item": null,
      "userErrors": [
        { "field": "itemId", "message": "Item not found" }
      ]
    }
  }
}

A successful response has "userErrors": [].

Common mutation errors

Error	Cause	Fix
`Item not found`	The item ID doesn’t exist in this workspace	Verify the item ID by running an `items` query first. Make sure you’re using the correct `WORKSPACE-ID`.
`Collection not found`	The collection name doesn’t exist and `autoCreate` is `false`	Either set `autoCreate: true` to create the collection, or check the collection name with a `filterPresets` query.

Rate limit errors

The API allows 5 requests per second per workspace. If a single token has access to multiple workspaces, each workspace gets its own 5 RPS budget.

When you exceed it, the API returns HTTP 429 with this body:


{
  "errors": [
    {
      "message": "Rate limit exceeded. Retry in 1 second(s).",
      "extensions": { "code": "RATE_LIMIT_EXCEEDED" }
    }
  ]
}

How to handle it:

Throttle your client to no more than 5 requests per second per workspace.
If you receive a 429, wait the number of seconds indicated in the error message before retrying.

Server errors

HTTP 5xx means a server-side error — the API is temporarily unavailable. Wait a moment and retry your request.

If the issue persists, contact support@archive.com.

API constraints

Constraint	Detail
Introspection	Disabled in production — you cannot query `__schema` or `__type` to explore the schema at runtime. Use this documentation as your reference.
Max query depth	10 — queries nested deeper than 10 levels will be rejected.