Skip to main content
Every failure returns the same shape, whatever went wrong and whichever endpoint it happened on.
Branch on code, never on message. Messages are written for people and are translated and reworded; codes are a contract and will not change under you.

Detecting a failure

data and error are mutually exclusive, so one check covers everything:

Status codes

Error codes

Authentication and permissions

Request problems

INVALID_PARAMETER usually carries details naming the parameter and listing what is accepted:

Resources

NOT_FOUND covers both “does not exist” and “not yours”, deliberately. Distinguishing them would confirm that an id is real, which is enough to map another customer’s resources by trying ids until the status changes.

Limits

Plan and subscription

These are all about what your plan permits, not what your request said. Retrying does not help; the account has to change.
The distinction that matters when handling these: FEATURE_LIMIT_EXCEEDED means you have the feature and ran out of it, so deleting resources or waiting for a billing period can clear it. The rest mean the plan does not include the feature at all, and only an upgrade changes the answer.
Call get_feature_limits before a large bulk create to fail early instead of halfway through.

Errors inside bulk operations

A bulk call does not return an error envelope when individual items fail. The request succeeded; some items did not. The outcome is inside data:
Check status first: success, partial_success, or error. Then walk results for the items that need attention.
A 200 on a bulk call does not mean every item worked. Always read summary.failed.
Set stop_on_error=true if you would rather the whole batch roll back at the first failure than land partially applied.

A retry policy that works

Retrying a 400 or a 403 wastes your rate limit on a request that cannot succeed until you change it.