Version 1 of 1 · · razie · in person · Current version

name
d3-f-errors
description
Errors — the shape of every error reply, how to act on one, the common codes, and how errors are written and catalogued. Get skills only from /api/v2/skills/d3.
feature
err
concepts
[error, catalogue]
tags
#skill #feature #d3skill #wip

d3-f-errors

Intro

Every refusal has one shape and says the next move.

Every refusal d2 makes has one shape and a one-line message that says the next move, with pointers to a skill section (see) for you and a Help section (help) for a person. Every code an API can return is catalogued in ApiErrors. Each feature's own codes are at the end of its d3-f- skill (#errors). Spec: Spec › api-conventions.

Essentials

  • R-err-1 MUST do what message says first; read see only when it isn't enough.
  • R-err-2 NEVER work around a refusal (another token, a different route, a shared credential): stop and say what was refused.
  • R-err-3 A 409 (E_DRAFT_CHANGED, E_IN_PROGRESS) is routine: re-read, merge, retry.
  • R-err-4 On E_INTERNAL report it with the request id; NEVER loop.
  • R-err-5 Every E_* an API returns is declared on its route's row in the code, in the same change; GET /api/v2/errors is generated from those rows (ApiErrors is retired), and the feature skill's Errors carries each code's fix line.

Concepts

error

A refused call. Also called: refusal, error reply. Fields: {ok: false, error: {code, message, reason?, see?, help?, …facts}} — message one line: what was wrong, then the next move; see = Skill:<name>#<anchor> (for you); help = a Help section (for a person).

error_read

  • Summary: message first; see one section; help to your person.
  • When: any reply with ok: false.
  • Needs: the reply body.
  • Call: GET /api/v2/skills/d3?role=<your role>&code=<E_X> → the code's line and the action it points to (d3-f-base › skill_pull).
  • Rules: R-base-2, R-err-1, R-err-2. Pull the code rather than follow the reply's see (it still names the old skills); never read a whole skill for one error. To a person, explain the error in plain words and give them the help link.
  • Errors: see #errors for the common codes.
  • Gotchas: —

error_write

  • Summary: one self-fixing line, a section pointer, catalogued.
  • When: designing or changing a route that refuses something.
  • Needs: the code, when it fires, the fix.
  • Call: the code on its route's row (errors, declared by the builder, Design › declared) and one line in the feature skill's Errors: `E_X` (status) — when → the fix. see #<action>. Check it with GET /api/v2/routes?code=E_X.
  • Rules: R-err-5. message is one line, self-fixing, works without any link. see is a skill section (never a whole skill), help a Help section; one is enough (both are filled from the one there is). On an AI token's call the message ends with the pointer (…send askedBy. See d3-f-cdn#file_store.). Error bodies carry no stack traces, file paths, tokens or internal ids.
  • Errors: —
  • Gotchas: —

catalogue

GET /api/v2/errors: every E_* d2 returns, generated from the route rows, with the fix line from each feature skill's Errors; ?format=json for the rows. Also called: error list; ApiErrors (the retired hand-kept topic).

catalogue_check

  • Summary: no dead pointers; no leaks in error bodies.
  • When: a guard run over errors.
  • Needs: GET /api/v2/errors?format=json.
  • Call: resolve each see and help against base d2's topics and sections.
  • Rules: GUARD-ERR-SEE: every see and help in the generated list resolves to an existing topic and section on base d2. An error body with a stack trace, file path, token or internal id is a finding.
  • Errors: —
  • Gotchas: —

Errors

  • E_AUTH (401) — no or bad credentials → d3-f-tokens. see #error_read
  • E_SCOPE (403) — your token or role may not do this → on a person action, suggest it to your person instead. see #error_read
  • E_TOKEN_SCOPE — the token isn't for this project → use this project's token. see #error_read
  • E_ARG (400) — a field missing or out of bounds → fix the field the message names. see #error_read
  • E_METHOD — wrong verb or route → use one the message lists. see #error_read
  • E_NOT_FOUND (404) — no such thing → check the id or name. see #error_read
  • E_NO_SECTION — no such anchor → pick from the section ids listed. see #error_read
  • E_DRAFT_CHANGED / E_IN_PROGRESS (409) — someone moved first → re-read, merge, retry. see #error_read
  • E_STATUS — the item's status doesn't allow that action → re-read it. see #error_read
  • E_RATE (429) — too fast → slow down, wait Retry-After. see #error_read
  • E_QUOTA — a plan limit → tell your person. see #error_read
  • E_SECRET (403) — a vault secret not allowed to your token, or allowed after you were minted → d3-f-vault › secret_read (mint a new token if the message says so). see #error_read
  • E_INTERNAL (500) — d2 failed → report it with the request id; don't loop. see #error_read
  • GUARD-ERR-SEE — a see/help pointer that doesn't resolve. see #catalogue_check