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

Two ceilings apply at once: a credit budget sized by your plan and a flat 5 requests per second, whichever you reach first. Both are per workspace and never shared — if one token covers several workspaces, each has its own budget. See Rate Limiting for the per-plan numbers and what each query costs.

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, and to no more credits per second than your plan refills. Whichever is lower for the query you’re running is the one that binds.
Read ratelimit: "<plan>";r=<credits remaining> off any response and self-throttle against it rather than discovering the ceiling.
If you receive a 429, honour the Retry-After header (or the number of seconds 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.