Documented steps

Parse the error body: {"error": {"type": "...", "message": "..."}} — type is the stable machine key; log both.
401 AUTHENTICATION_REQUIRED / UNAUTHORIZED: missing, malformed, or revoked Bearer token. Check the header format 'Authorization: Bearer pat...' with no stray whitespace.
403 INVALID_PERMISSIONS_OR_MODEL_NOT_FOUND: the token lacks a scope, the base isn't in the token's resource grants, or the user's collaborator role is too low. Airtable deliberately blurs 'no permission' and 'doesn't exist'.
404 NOT_FOUND / TABLE_NOT_FOUND / MODEL_ID_NOT_FOUND: wrong or deleted base/table/record id — verify ids via the Meta API (app.../tbl.../rec... prefixes must match the slot they're used in).
422 INVALID_REQUEST / INVALID_VALUE_FOR_COLUMN: body shape or field values don't match the schema — wrong cell type, unknown select option (retry with typecast:true if coercion is intended), writing to computed fields, or an oversized records array (split the batch).
429: rate limited — sleep 30 seconds, then retry (see the rate-limits route).
Docs: https://airtable.com/developers/web/api/errors

Known gotchas

Because 403 doubles as 'not found', don't trust the message text — systematically check scope, then token base grants, then the id itself.
PATs inherit the creator's permissions: correct scopes + correct base grant can still 403 if the human behind the token lost editor access.
422 messages name the offending field — surface them verbatim in logs; they're the fastest path to the broken column.
Retrying 4xx errors (other than 429) is futile — they're deterministic; fix the request instead of backoff-retrying.

Give your agent this knowledge — and 15,600+ more routes

One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus: claude mcp add --transport http waymark https://mcp.waymark.network/mcp

Diagnose Airtable Web API error responses (401/403/404/422/429)

Documented steps

Known gotchas

Related routes

Give your agent this knowledge — and 15,600+ more routes

Need this verified for your stack — or a route we don't have yet?