Errors

Errors are JSON with a single error field carrying a stable, machine-readable code, for example {"error": "invalid_csr"}. Match on that code together with the status; there is no human-readable message field to parse.

Status codes

Status	Meaning	What to do
400	Malformed request - bad JSON, unparseable CSR, invalid parameter	Fix the request. Retrying is pointless
401	Missing, malformed, unknown or revoked token	Check the token; reissue if revoked
403	Valid token, but its scopes do not cover this endpoint	Add the required scope - a new token, scopes are fixed at creation
404	Not found, or not visible to your tenant	See below
429	Rate limit exceeded	Back off - see rate limits
5xx	Server-side fault	Retry with backoff. If it persists, report it

Why 404 and not 403 for another tenant’s data

Requesting a certificate that belongs to a different tenant returns 404, not 403. This is intentional: a 403 would confirm the object exists, which is itself a leak. Isolation is enforced in the database, so from your token’s perspective the row genuinely does not exist.

The practical consequence: a 404 on an ID you believe is correct usually means wrong tenant or wrong region, not a deleted object.

Retry safety

Method	Safe to retry
GET	Always
POST .../renew	On 429 and 5xx only. Not idempotent - read state before retrying (see below)

Renewal creation is not idempotent in v1: there is no idempotency key, so a blind retry after an ambiguous timeout can open a second renewal. Check GET /v1/requests for the certificate before retrying.