Errors & Zero Results

HTTP Status Codes

All API responses use standard HTTP status codes. The table below lists every code you may encounter and when to expect it.

Error Response Shape

All error responses share the same JSON structure:

{
  "error": {
    "code": "LICENSE_REGION_MISMATCH",
    "message": "No provider met the required license-region rule.",
    "status": 422,
    "requestId": "req_01K...",
    "field": "constraints.licenseRegionCodes",
    "recoverable": true,
    "suggestedAction": "Remove or broaden the required license region."
  }
}

Every v2 response includes X-Orita-Request-Id for tracing. The code is stable for programmatic matching. The recoverable field tells you whether retrying makes sense.

Zero-Result Handling

When POST /api/v2/resolutions finds no provider matching the constraints, it returns status: "zero_results" (HTTP 200) with an explanation:

{
  "resolutionId": "res_01JZBK...",
  "status": "zero_results",
  "options": [],
  "totalProviders": 20,
  "evaluatedSlots": 0,
  "zeroResultReasons": [
    {
      "reasonCode": "NO_LANGUAGE_MATCH",
      "description": "No providers in your network speak the requested language.",
      "affectedProviders": 20,
      "suggestion": "Add the language attribute to more providers, or relax this constraint."
    }
  ]
}

Reason Codes

Retry Logic

For 429 and 5xx responses, use exponential backoff. Never retry 4xx errors (except 429) — they indicate a problem with the request itself.

// Exponential backoff example
async function resolveWithRetry(payload, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const res = await fetch('/api/v2/resolutions', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.ORITA_API_KEY}`,
          'Idempotency-Key': `${payload.sessionId}-${attempt}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(payload),
      });

      if (res.status === 429) {
        const retryAfter = parseInt(res.headers.get('Retry-After') ?? '5');
        await sleep(retryAfter * 1000);
        continue;
      }

      if (res.status >= 500) {
        await sleep(Math.pow(2, attempt) * 1000); // 1s, 2s, 4s
        continue;
      }

      return await res.json();
    } catch (err) {
      if (attempt === maxRetries - 1) throw err;
      await sleep(Math.pow(2, attempt) * 1000);
    }
  }
}

function sleep(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

Hold Expiry Handling

Holds expire after 10 minutes. Resolutions expire after 5 minutes. Both return 410 Gone when accessed after expiry.

const holdRes = await orita.resolutions.hold(optionId);

// If hold expires before confirmation:
try {
  await orita.resolutions.confirm(holdId);
} catch (err) {
  if (err.status === 410) {
    // Re-resolve: the slot may have been taken
    const newResolution = await orita.resolutions.resolve({ ... });
    // Show new options to user
  }
}

Idempotency

All POST /api/v2/resolutions calls require an Idempotency-Key header.

Best practice: derive the key from your session ID + a hash of the request payload.

import { createHash } from 'crypto';

function idempotencyKey(sessionId: string, payload: object): string {
  const hash = createHash('sha256')
    .update(JSON.stringify(payload))
    .digest('hex')
    .slice(0, 12);
  return `${sessionId}-${hash}`;
}

// Usage
const key = idempotencyKey(session.id, resolutionPayload);

await fetch('/api/v2/resolutions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ORITA_API_KEY}`,
    'Idempotency-Key': key,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(resolutionPayload),
});