Errors

Errors are application/problem+json (RFC 9457):

{
  "type": "https://developers.bisket.ai/errors/validation_failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "1 field is invalid.",
  "instance": "/v1/locations/…/orders",
  "code": "validation_failed",
  "request_id": "req_01JC…",
  "errors": [{ "field": "items", "code": "required", "message": "…" }]
}

Branch on code, never on title or detail. Quote request_id to support. Codes may be added within v1: handle an unknown code by its HTTP status. Every code has its page: the error catalogue.

errors.ts

// Errors: every non-2xx answer throws a BisketError; branch on `code`, quote `requestId` to support.
import { BisketError, createBisket } from '@bisket-ai/partner-sdk';

export async function main(env: { apiKey: string; locationId: string }) {
  const bisket = createBisket({ apiKey: env.apiKey });
  try {
    await bisket.POST('/v1/locations/{location_id}/orders', {
      params: { path: { location_id: env.locationId } },
      body: {
        external_id: `ERR-${Date.now()}`, partner_order_number: 'ERR', customer: { first_name: 'Ana' },
        items: [], subtotal: { amount: 100, currency: 'HTG' }, collected_by: 'partner',
        payment: { method: 'card', status: 'paid', amount: { amount: 100, currency: 'HTG' } },
      },
    });
    return { code: null };
  } catch (e) {
    if (!(e instanceof BisketError)) throw e;
    // e.status 422, e.code 'validation_failed', e.errors[0].field 'items', e.requestId 'req_…'
    return { status: e.status, code: e.code, field: e.errors[0]?.field, requestId: e.requestId };
  }
}

Retry only 429, 5xx and 409 idempotency_in_progress, with the same Idempotency-Key and honoring Retry-After.