docs(errors): sync error reference with reviewed envelope behavior#185
Merged
Conversation
PR #183 merged before the agentmail-api branch (sid/agent-friendly-errors, PR #586) went through its review rounds; this catches the reference page up to what the API now actually emits: - Intro example: the wire emits the subclass name (MissingPermissionError, not ForbiddenError) and the default fix carries the scope caveat. - missing_authorization: three variants (missing header, wrong/missing Bearer scheme, empty key after a correct scheme) — the message states which. - missing_permission: fixes are cause-derived — grantable vs scope-derived vs verification-gated (POST /v0/agent/verify) vs agent_verify itself. - unrestricted_key_required: covers all three gates (unrestricted child creation, permissions clear, modifying an unrestricted key); the fix says which fired. - message_rejected: distinguishes send block-list entries (DELETE /v0/lists/send/block/{entry} at the creating scope) from active allow-list misses (POST /v0/lists/send/allow — nothing to delete). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ds 9-10) - Intro example shows the actual wire shape: name 'ForbiddenError', message 'Forbidden' — legacy name/message are preserved for compatibility, so the guidance is branch on code/fix, and fix is documented as optional. - missing_permission: message stays 'Forbidden' (event gates keep '<permission> is forbidden'); the permission is named in fix. - not_found documents the deliberate hiding of out-of-scope and restricted-label resources — a correct id can still 404. - missing_authorization adds the whitespace-in-key variant. - limit_exceeded documents the OTP live-vs-expired remedy split. - conflict documents the failed-without-completing retry window. - message_rejected: itemized — scope-aware block-entry DELETE paths (broader- scope entries need a broader-scoped key), read-only entries go to support, allow-list miss on unverified agent orgs points at verification. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…arning - api-403-error: teach read-the-fix first and distinguish the bodyless API gateway 403 from application 403s; cross-org resources are a deliberate 404 not_found (only the inbox-key-on-pod-route case is a 403); suppressed recipients carry message_rejected with entry-specific remedies; and the 'we do not restrict your API key' section is replaced — keys DO carry granular permissions now, with missing_permission naming the gap in fix. - agent-onboarding: unverified sends no longer fail silently — they return message_rejected with a fix pointing at POST /v0/agent/verify. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
PR #183 merged on 07-10, before agentmail-api#586 went through its review rounds — several error behaviors changed during review, so the merged reference page describes the pre-review envelope. This syncs it to what the API branch now actually emits:
name/messageare preserved for backward compatibility (ForbiddenError/Forbidden; event-permission gates keep<permission> is forbidden), so the page teaches branch-on-code/fix, documentsfixas optional, and the default fix carries the cannot-mint-a-key and scope caveats. (Earlier revisions of this PR tracked the mid-review subclass-name behavior; api#586 rounds 9–10 restored the legacy names for wire compatibility.)missing_authorization: now three variants — missing header, wrong/missing case-sensitiveBearerscheme, or a correct scheme with an empty key value; the message states which.missing_permission: fixes are cause-derived — a grantable permission missing from the key, a scope-derived denial (organization_read), a verification-gated permission (completePOST /v0/agent/verifyfirst), oragent_verifyitself (only available while an unverified agent org still needs verification).unrestricted_key_required: covers all three gates (unrestricted child creation,permissions: nullclear, modifying a currently-unrestricted key); the responsefixsays which fired.message_rejected: distinguishes send block-list entries (DELETE /v0/lists/send/block/{entry}at the scope where the entry was created) from active allow-list misses (POST /v0/lists/send/allow— there is no block entry to delete).Verified against agentmail-api
afa5aa77: all 24AGENT_ERROR_CODEShave matching###anchors on this page and vice versa.Note: https://docs.agentmail.to/errors currently 404s even though #183 merged and the page is wired into
docs.yml— the page doesn't appear to have been published to the live site yet, which is worth checking before agentmail-api#586 ships (every error response links to it).🤖 Generated with Claude Code