Errors

Every error is JSON with an error field, sent with Cache-Control: no-store. Some carry one more field that tells you what to do next.

{ "error": "forbidden", "requiredScope": "review:write" }

Status	error	Extra fields	What to do
400	A sentence naming the problem, such as limit must be a positive integer	none	Fix the request. Retrying it unchanged gets the same answer.
401	unauthorized	none	The token is missing, malformed, unknown or revoked. Mint a new one.
403	forbidden	requiredScope	The token lacks that scope. Mint a token that has it.
404	not found	none	The id does not exist or belongs to another account.
409	invalid_action	actions	The card no longer accepts that verb. Re-render from actions.
409	use_send	message, actions	A Gmail card was sent to /answer. Use POST /review/{id}/send.
409	rejected	message	A settled refusal, such as a card that was already handled.
409	this address unsubscribed and cannot be unblocked	none	The address opted out, so it stays on the block list.
429	rate limited	Retry-After header	Wait that many seconds, then retry.
500	server misconfigured	none	Our fault. Retrying will not help until we fix it.
503	temporarily unavailable	Retry-After header	Infrastructure, not your request. Retry the same call unchanged.
503	delivery_pending, unavailable	message, Retry-After header	Gmail sends only: delivery is still being confirmed, or the mail service is down. Retry the same send.

400: the request is wrong

The message is written to be shown to a developer, so log it. Common ones: body must be JSON (the body is not a JSON object), cursor is not valid (pass back the nextCursor you were given, unmodified), limit must be a positive integer, text required. Unknown fields on a workflow write are also a 400, so a typo in a field name fails loudly instead of being ignored.

401 and 404 look alike on purpose

A card, lead or workflow id from another account is a 404, exactly as if it did not exist, so a token cannot probe for ids it should not see. An unknown or revoked token is always 401, never 404.

409: re-read, don't retry

A 409 is a decision, not an outage. Two people, or a person and the trust ladder, can act on the same card, so a verb that was valid when you listed the queue can be gone a second later:

{ "error": "invalid_action", "actions": ["snooze", "dismiss"] }

Draw the card again from actions and move on. rejected carries a message a person can read, for example This was already handled.

429 and 503: back off and retry

Both send Retry-After in seconds. It is computed from the bucket, so retrying sooner only spends another request. See Rate Limits for the numbers. A 503 means the token could not be checked, the limiter was down for a write, or a delivery answer was lost. Retrying is safe: approving a card that already shipped comes back as a 409, and agent messages take a clientRequestId so a retried send is not delivered twice.