Error Handling

All Pryzma API errors return JSON with a single error field and an appropriate HTTP status code:

json

{"error":"invalid_token"}

Error codes

| Code | HTTP | Description | |---|---|---| | missing_bearer_token | 401 | No Authorization header on the request | | invalid_token | 401 | Token expired, malformed, or revoked | | insufficient_scope | 403 | Token lacks the required scope for this operation | | invalid_body | 400 | Request body missing, not valid JSON, or missing required fields | | invalid_org_id | 400 | An organisation ID in the path or body is not a valid UUID | | ledger_unavailable | 502 | TigerBeetle cluster is temporarily unreachable — retry with backoff | | internal_error | 500 | Unexpected server error — contact support if persistent |

Idempotency and retries

Every mutating request (POST, PATCH, DELETE) requires a Pryzma-Idempotency-Key header containing a UUID you generate:

Pryzma-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Replay semantics: If you send the same idempotency key within 24 hours, the API returns the stored response from the first execution — the operation is not repeated. This makes it safe to retry on:

Network timeouts
Connection resets
502 / 503 responses (server-side transient errors)

Do not reuse an idempotency key for a semantically different operation. A new transfer to a different recipient must use a new key, even if the earlier attempt failed.

On ledger_unavailable (502), wait at least 1 second before retrying. The TigerBeetle cluster recovers automatically; typically resolves within a few seconds.

Handling errors in code

javascript

async function createAccount(payload, idempotencyKey) {
const res = await fetch('https://api-dev.pryzma.global/v1/accounts', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
    'Pryzma-Idempotency-Key': idempotencyKey,
  },
  body: JSON.stringify(payload),
});

if (!res.ok) {
  const { error } = await res.json();
  if (error === 'ledger_unavailable') {
    // Retry with the same idempotency key — safe.
    throw new RetryableError(error);
  }
  throw new Error(error);
}

return res.json();
}