Fail explicitly. Retry safely.

Map LinkCode HTTP responses to explicit resolution states, retry safely and use idempotency for future API management mutations.

Resolution status codes

PropertyTypeDescription

200found

A valid destination was selected.

404not_found

The normalized code does not exist.

410expired

The code expiration time has passed.

423unavailable

The code exists but cannot resolve.

502manifest_invalid

The manifest provider returned an invalid v1 shape.

503service_unavailable

A required resolver dependency is unavailable.

Retry policy

✓Do not retry 404, 410 or 423 automatically.
✓Retry 429 and 5xx with exponential backoff and full jitter.
✓Cap retries and surface the final failure to the caller.
✓Use Idempotency-Key for every future POST or mutation retry.
✓Log request IDs, never API keys or raw personal data.

const delay = Math.min(30_000, 500 * 2 ** attempt);
const jitter = Math.random() * delay;
await new Promise((resolve) => setTimeout(resolve, jitter));