Errors and retries

Lumin Shield ↗Open panel ↗

Response codes and safe request retries.

Error format

{
  "error": {
    "code": "validation",
    "message": "domain must be a hostname",
    "details": {"field": "domains"}
  }
}

Branch on code, not the wording of message. Use details.field for form validation.

Common responses

Status	Code	Action
400	bad_json, validation	Correct the request format.
401	unauthorized, token_invalid	Check the key or session; do not retry in a loop.
403	forbidden, user_required, plan_restricted	Check role, authentication type and plan.
404	not_found	Check the ID and organisation. Inaccessible resources may deliberately appear missing.
409	domain_taken, in_use	Resolve the data conflict or dependency.
422	validation, quota_exceeded, target_invalid	Correct data, resource choice or plan quota.
429	rate_limited	Wait and reduce request frequency.
500 / 502 / 503	internal or connection error	Retry reads with a delay.

Retries

Use bounded retries with exponential backoff and jitter for GET. Do not retry every 4xx response.

A POST timeout leaves the result uncertain: the server may already have saved the operation. Check existing resources before retrying. Do not assume support for idempotency keys or webhooks unless the API contract documents it.

Logging

Log the method, secret-free path, status and error code. Never log Authorization, tokens, passwords or full key-creation responses.