Errors

{
  "error": "Bad Request",
  "message": "did is required",
  "code": 400
}

{
  "error": "Unauthorized",
  "message": "exactly one Signature-Input and one Signature header are required",
  "code": 401,
  "class": "signature_invalid"
}

{
  "error": "Forbidden",
  "message": "authority not bound to this subject",
  "code": 403,
  "class": "standing_failure",
  "failed_step": "authority_binding"
}

# Fire a request, capture status and body separately.
BASE=https://phosra-api-sandbox-production.up.railway.app
http=$(curl -s -o /tmp/phosra-err.json -w '%{http_code}' \
  -X POST "$BASE/api/v1/enforcement-confirmations" \
  -H 'Content-Type: application/json' -d '{}')

# Pull the machine-readable fields off the envelope (jq).
class=$(jq -r '.class      // "none"' /tmp/phosra-err.json)   # signature_invalid | standing_failure | …
step=$( jq -r '.failed_step // "none"' /tmp/phosra-err.json)  # only on standing_failure

case "$http" in
  2*)          echo "ok" ;;
  429|5*)      echo "retryable ($http) — back off and retry" ;;
  401)         echo "re-sign and retry once ($class)" ;;
  *)           echo "fatal $http · class=$class · failed_step=$step"
               jq -r '.message' /tmp/phosra-err.json ;;   # log-only prose
esac
# => fatal 401 · class=signature_invalid · failed_step=none  (missing signature)

import {
  PhosraClient,
  PhosraApiError,
  PhosraRateLimitError,
} from '@phosra/sdk';

const RETRYABLE = new Set([429, 500, 502, 503]);

// One handler for every Phosra failure. The typed subclasses map to status;
// the OCSS `class` and `failed_step` ride in `err.details` (the parsed envelope).
function classify(err: unknown): 'retry' | 'reauth' | 'fatal' {
  if (err instanceof PhosraRateLimitError) return 'retry';   // 429
  if (err instanceof PhosraApiError) {
    const status = err.statusCode;                            // 401, 403, 404, 409, 422, 5xx
    const cls = (err.details?.class as string) ?? 'none';     // e.g. "standing_failure"
    const step = (err.details?.failed_step as string) ?? 'none';
    if (RETRYABLE.has(status)) return 'retry';
    if (status === 401) return 'reauth';                      // re-sign, retry once
    console.error(`fatal ${status} · class=${cls} · failed_step=${step}`);
    return 'fatal';                                           // 400/403/404/409/422 — fix the request
  }
  throw err;                                                  // not an API error — re-throw
}

try {
  await phosra.families.list();
} catch (err) {
  switch (classify(err)) {
    case 'retry':  /* back off (see rate-limit section) and retry */ break;
    case 'reauth': /* refresh/re-sign, retry exactly once        */ break;
    case 'fatal':  throw err;
  }
}

# openapi-generator (-g python) raises phosra_client.exceptions.ApiException,
# which carries .status (int) and .body (the raw JSON envelope).
import json, time
from phosra_client.exceptions import ApiException

RETRYABLE = {429, 500, 502, 503}

def call_with_handling(fn, *args, **kwargs):
    try:
        return fn(*args, **kwargs)
    except ApiException as e:
        env = {}
        try:
            env = json.loads(e.body or "{}")   # {"code":…,"class":…,"failed_step":…}
        except ValueError:
            pass
        cls = env.get("class", "none")          # signature_invalid | standing_failure | …
        step = env.get("failed_step", "none")   # only on standing_failure

        if e.status in RETRYABLE:
            time.sleep(1)                        # back off, then retry
            return call_with_handling(fn, *args, **kwargs)
        if e.status == 401:
            raise RuntimeError(f"re-sign and retry once (class={cls})") from e
        # 400 / 403 / 404 / 409 / 422 — deterministic, do not retry
        raise RuntimeError(
            f"fatal {e.status} · class={cls} · failed_step={step} · {env.get('message')}"
        ) from e

// openapi-generator (-g go) returns a *phosra.GenericOpenAPIError; the HTTP
// response (with .StatusCode) is the second return value.
import (
    "encoding/json"
    "errors"
    "fmt"
    "net/http"

    phosra "example.com/phosra"
)

type envelope struct {
    Code       int    `json:"code"`
    Class      string `json:"class"`       // signature_invalid | standing_failure | …
    FailedStep string `json:"failed_step"` // only on standing_failure
    Message    string `json:"message"`
}

func classify(httpRes *http.Response, err error) error {
    if err == nil {
        return nil
    }
    status := 0
    if httpRes != nil {
        status = httpRes.StatusCode
    }
    var apiErr *phosra.GenericOpenAPIError
    var env envelope
    if errors.As(err, &apiErr) {
        _ = json.Unmarshal(apiErr.Body(), &env) // parse the envelope for class/failed_step
    }
    switch {
    case status == 429, status >= 500:
        return fmt.Errorf("retryable %d: back off and retry: %w", status, err)
    case status == 401:
        return fmt.Errorf("re-sign and retry once (class=%s): %w", env.Class, err)
    default: // 400/403/404/409/422 — deterministic, fix the request
        return fmt.Errorf("fatal %d · class=%s · failed_step=%s · %s",
            status, env.Class, env.FailedStep, env.Message)
    }
}

// resp, httpRes, err := client.QuickSetupAPI.SetupQuickPost(ctx)....Execute()
// if e := classify(httpRes, err); e != nil { log.Fatal(e) }

# Read the reset, wait, retry
RESET=$(curl -s -D - -o /dev/null "$BASE/api/v1/families" \
  -H "Authorization: Bearer $PHOSRA_API_KEY" \
  | grep -i '^x-ratelimit-reset:' | tr -d '\r' | awk '{print $2}')
sleep $(( RESET - $(date +%s) ))

try {
  const families = await phosra.families.list();
} catch (err) {
  if (err.status === 429) {
    const resetAt = Number(err.headers['x-ratelimit-reset']);
    const waitMs = Math.max(0, resetAt * 1000 - Date.now());
    await new Promise((r) => setTimeout(r, waitMs));
    // retry
  }
}