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.

HTTPCodeMeaningRetry?
400invalid_argumentA field is missing or malformed. message names it.No, fix the request
401unauthenticatedThe credential is missing, expired or invalid.After getting a new token
403permission_deniedThe 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
404not_foundNo site with this externalId.No
409already_existsThe idempotencyKey was already used with a different request.No, use a new key
429resource_exhaustedThe request body is too large.No, send a smaller request
503unavailableTemporary problem on our side.Yes, with backoff
504deadline_exceededThe call did not finish in time.Yes, with backoff
500internalUnexpected 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.

On this page