Errors
A call either fails as a whole with an HTTP error, or succeeds with some records rejected. The two are reported differently.
A rejected record is a normal result. The call returns HTTP 200 and the result
carries an error object with a stable string code and a readable message. Fix
the data and send the record again.
A failed call returns an HTTP error status and a JSON body:
{
"code": "unauthenticated",
"message": "invalid API credential"
}Branch on the HTTP status or on code. message is for people, not for parsing.
| HTTP | Code | Meaning | Retry? |
|---|---|---|---|
| 400 | invalid_argument | A field is missing or malformed. message names it. | No, fix the request |
| 401 | unauthenticated | The credential is missing, expired or invalid. | After getting a new token |
| 403 | permission_denied | The credential lacks the scope for this call, or, for SiteService, the workspace does not have the API or Site Scanner enabled or the requested tier is not enabled for it. | No |
| 404 | not_found | No site with this externalId. | No |
| 409 | already_exists | The idempotencyKey was already used with a different request. | No, use a new key |
| 429 | resource_exhausted | The request body is too large. | No, send a smaller request |
| 503 | unavailable | Temporary problem on our side. | Yes, with backoff |
| 504 | deadline_exceeded | The call did not finish in time. | Yes, with backoff |
| 500 | internal | Unexpected error. | Yes, with backoff |
Retries and idempotency
A call can time out after the server has done the work, so writes are safe to
retry. UpsertCustomer takes an idempotencyKey: repeat the call with the same key
and the same record and you get the original response, with nothing written twice.
CreateSite is keyed by your externalId: submitting the same id with the same
address again returns the current site and does not start a second scan, unless the
site's status is SITE_STATUS_FAILED: then the scan runs again.