Errors

Preview — documented before it ships

This is the error contract the API will honor.

There is one error envelope for every 4xx and 5xx. Agents branch on code; humans read message; you write one parse path. No 3xx ever carries an error body.

The envelope

{
  "error": {
    "type": "invalid_request",
    "code": "ambiguous",
    "message": "12 titles match \"office\". Pass a slug: or steam: identifier.",
    "docsUrl": "https://docs.doesitarm.com/api/errors/#ambiguous",
    "suggestions": [{ "slug": "microsoft-office", "title": "Microsoft Office", "score": 0.82 }],
    "requestId": "req_01J5K6Q8Z9"
  }
}

• type — coarse family: invalid_request, rate_limited, auth, server. (ambiguous is a code, sent under type: invalid_request.)
• code — the precise branch (closed set below). Branch on this.
• message — human-readable; names the offending field where relevant.
• docsUrl / upgradeUrl — where to read more, or how to unblock.
• suggestions — present on ambiguous: candidates to re-query with.
• requestId — quote it to support.

The full table

Case	HTTP	type	code	What to do
Unknown title	200	—	—	Not an error. You get a Verdict with status: "unknown"; read alternatives.
Ambiguous lookup	409	invalid_request	ambiguous	Pick from suggestions[]; re-query with a slug:/steam: id.
Invalid parameter	422	invalid_request	invalid_param	Fix the field message names (e.g. a bad chip).
Auth required	401	auth	auth_required	Add an API key (paid-only route).
Auth invalid	401	auth	auth_invalid	Rotate the key — bad, revoked, or expired.
Forbidden (tier)	403	auth	plan_required	Upgrade; docsUrl → pricing.
Rate limited	429	rate_limited	rate_limited	Wait Retry-After, or upgrade via upgradeUrl.
Server error	5xx	server	internal	Retry with backoff; quote requestId.

unknown and stale are not errors

A title with no data returns 200 with status: "unknown". A title past its freshness window returns 200 with stale: true. Read them as verdicts — see The Verdict object and Caching & freshness.

Worked example — ambiguous lookup (409) {#ambiguous}

A bare name with several strong matches doesn’t guess — it asks you to disambiguate:

curl https://api.doesitarm.com/v1/verdicts/office

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": {
    "type": "invalid_request",
    "code": "ambiguous",
    "message": "12 titles match \"office\". Pass a slug: or steam: identifier.",
    "docsUrl": "https://docs.doesitarm.com/api/errors/#ambiguous",
    "suggestions": [{ "slug": "microsoft-office", "title": "Microsoft Office", "score": 0.82 }],
    "requestId": "req_01J5K6Q8Z9"
  }
}

Re-query with one of the suggestions: GET /v1/verdicts/slug:microsoft-office. The other worked example — a 429 and the upgrade path — lives on Rate limits.