Error Handling

This page covers how to handle errors and edge cases when calling the Quantropy API—including quantum-state-related exceptions and fallbacks.

HTTP/gRPC status codes

Code	Meaning	What to do
401	Unauthorized	Invalid or missing API key. Check key and headers.
402	Payment Required	Insufficient $QPY balance. Top up or reduce usage.
429	Too Many Requests	Rate limit exceeded. Retry after the delay in Retry-After (or back off exponentially).
503	Service Unavailable	Temporary overload or maintenance. Retry with backoff.
5xx	Server error	Transient failure. Retry with backoff; contact support if persistent.

Quantum-state-related exceptions

The API can return errors that are specific to quantum job state or hardware:

• Job failed — The entropy job could not be completed (e.g. QPU error, timeout). The request did not produce verifiable entropy; you did not get a Quantum Job ID. Action: Retry the request. Treat as transient unless it persists.

• Job delayed or queued — In high load, your job may be queued. You might get a different status or a longer response time. Action: Implement timeouts and retries; consider exponential backoff.

• Hardware unavailable — Rarely, the fleet may be temporarily unable to serve a request. Action: Retry; if your use case allows, consider a fallback (see below).

Exact error codes and messages depend on the API version; check the response body or SDK docs for machine-readable codes.

Retries and idempotency

• Retries — For transient errors (503, 429, job failed), retry with exponential backoff. Cap the number of retries and respect Retry-After when present.

• Idempotency — Each new request creates a new job and a new Quantum Job ID. Retrying the same logical operation (e.g. “get entropy for this round”) by issuing a new request is safe but yields new entropy. If you need to “retry” without changing the outcome, you must not issue a second entropy request for that same logical event—otherwise you get two different random values. So: retry failed requests (no entropy received); do not retry successful requests (you already have entropy and a Job ID).

Fallbacks

For availability-critical applications, you may want a fallback when Quantropy is temporarily unavailable:

• Defer — Postpone the operation (e.g. “draw lottery when API is back”).

• Degrade — Use a local PRNG or another source only when Quantropy fails, and clearly label that outcome as non-verifiable (e.g. for logging or user disclosure). Do not mix verifiable and non-verifiable entropy in the same security-sensitive flow without clear semantics.

Best practice: treat Quantropy as the primary source of verifiable entropy; use fallbacks only for resilience, and document when fallback entropy was used so it can be audited.

For API details: API Reference. For SDK usage: SDK Libraries.