Skip to main content
Errors covers the shape and the codes. This is how to build a client around them once, rather than checking "error" in payload at four hundred call sites.

One place that unwraps

Every call now either returns data or raises something with a code on it.

Deciding what to do with each code

Group by what the caller should do, not by number:
details is the useful part of an INVALID_PARAMETER: it names the parameter and usually lists what would have been accepted, which is exactly what your validation message should say.

Retry only what can change

Retrying a 403 burns your rate limit on a request that cannot succeed until you change something.

Bulk calls need their own check

A bulk call that partially fails is a 200. Nothing above catches it:
Or pass stop_on_error=true and let the whole batch roll back instead. Choose per operation: partial application is fine for a cleanup job and usually wrong for anything a user is watching.

Logging what will help later

Never log the key, and never log a whole request that carries one. Keys are shown once at creation and a leaked one has to be revoked and replaced everywhere it was deployed.

Two shapes that escape the envelope

200, data.status = "partial_success". Read summary.failed.
get_org_metrics_batch returns data.status = "error" with a message, inside a 200, when a filter cannot be served from rollups. See Filtering.