Errors and retries

Alkax APIs use HTTP status codes for the main outcome and structured response bodies for machine-readable and human-readable detail.

Common status codes

Status	Meaning	Client action
400	Invalid request or validation failure	Correct the request before sending it again
401	Missing, malformed, invalid, expired, or revoked credential	Replace the credential
402	A paid subscription is required	Activate or renew the project owner's subscription
403	Authenticated but not allowed	Check scopes, access, and tenant ownership
404	Resource not found or not visible to this tenant	Verify the stable ID; do not probe repeatedly
409	Lifecycle, duplicate, or idempotency conflict	Read the current resource and reconcile
429	Rate or monthly plan allowance reached	Honour Retry-After, reduce usage, or upgrade the plan
5xx	Temporary server failure	Retry a bounded number of times with exponential backoff

Safe retry pattern

1. Set a request timeout.
2. Retry only network failures, 429, and documented transient 5xx outcomes.
3. Reuse the same idempotency key when retrying the same logical create request.
4. Add exponential backoff with jitter.
5. Stop after a bounded number of attempts and surface the failure for review.

Never retry a 400 response unchanged. Avoid creating a new idempotency key merely because the first response was lost; that can turn one intended operation into two.

Localised messages

Some APIs localise human-readable messages from Accept-Language. Do not make program logic depend on translated text. Persist the status, stable resource ID, and machine-readable error code instead.