Errors

Every failing request returns the same body, whatever the status and whatever it was you asked for. There is no second error format to handle.

This is a real response, copied from q=set_code:obf on 2026-08-27 — a query written in response spelling instead of query spelling:

{
  "error": {
    "code": "INVALID_QUERY",
    "message": "Unknown search field \"set_code\" at position 0. The full list of searchable fields is in details.valid_fields.",
    "details": {
      "field": "set_code",
      "position": 0,
      "valid_fields": ["abilities.name", "abilities.text", "abilities.type", "artist", "…"]
    },
    "request_id": "20132829-00df-41c8-95bc-db9305fb54ed"
  }
}

Handling errors

The shape is uniform enough that one helper covers the whole API:

class ApiError extends Error {
  constructor(
    readonly code: string,
    readonly status: number,
    readonly requestId: string,
    message: string,
  ) {
    super(message);
  }
}

export async function json<T>(res: Response): Promise<T> {
  if (res.ok) return res.json() as Promise<T>;

  const body = await res.json().catch(() => null);
  const err = body?.error;

  throw new ApiError(
    err?.code ?? "UNKNOWN",
    res.status,
    err?.request_id ?? res.headers.get("X-Request-Id") ?? "",
    err?.message ?? res.statusText,
  );
}

Retry rules

The complete taxonomy

21 codes, grouped by status family. Codes are a published contract: once shipped, they do not change meaning, and new ones are added only when a failure mode becomes distinguishable.

400 — bad request

The request never reached the database. Fix the caller; every retry returns the same body.

401 — unauthenticated

No usable key was presented on a route that requires one.

404 — not found

A statement about the catalogue, or about the path. Cache it; do not poll it.

413 / 415

Request-shape problems that deserve their own status.

500 / 503 — our fault

A client error never lands here. If you see a 5xx caused by a request you sent, that is a bug and we want the request id.

Reading details

The useful part of a 400 is usually in details, not in the message: