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.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 insidedata:
status first: success, partial_success, or error. Then walk results for the items that need attention.
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
400 or a 403 wastes your rate limit on a request that cannot succeed until you change it.