Handling errors

Every BeeL. endpoint reports failures with an HTTP status for the broad outcome and a JSON body for the specifics. If you only remember one thing: switch on the error code, log meta.request_id, and never parse the human message — it's localized and rewritten freely.

Response shape

Every error response carries two contracts at once (additive, non-breaking):

{
  "type": "https://docs.beel.es/errors/INVOICE_NO_LINES",
  "title": "INVOICE_NO_LINES",
  "detail": "La factura debe tener al menos una línea",
  "instance": "/v1/invoices/abc-123",
  "errors": [],
  "success": false,
  "error": {
    "code": "INVOICE_NO_LINES",
    "message": "La factura debe tener al menos una línea",
    "details": {}
  },
  "meta": {
    "timestamp": "2026-05-21T10:00:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

The fields pair up: title = error.code, detail = error.message, errors[] mirrors error.details. The type URI is a clickable deep link to that error's reference page. meta.request_id matches the X-Request-Id response header — quote it in support tickets.

Localisation

Pass Accept-Language to receive detail / error.message in es (default), en, or ca. The codes themselves are language-neutral — branch on code, never on the message: the same code produces different text per locale.

curl -H "Authorization: Bearer beel_sk_test_..." \
     -H "Accept-Language: en" \
     https://app.beel.es/api/v1/invoices/abc-123

Status codes

The status says what the protocol thinks happened; the code says what BeeL. thinks happened. Use the status to pick a coarse strategy and the code for the precise one:

Retries and idempotency

The single most expensive mistake in error handling is getting the Idempotency-Key semantics wrong on retry — it either creates duplicate invoices or replays a cached failure:

One nuance on 429: request-rate 429s are emitted by the edge filter with a minimal body, while monthly-quota 429s (QUOTA_EXCEEDED) come from the application with the full envelope. Rely on the status and headers, not the body shape — see Rate limits.

The codes you'll actually hit

These cover the vast majority of integration failures. Everything else lives in the error reference.

Distinctions worth internalizing

• 401 vs 403 — 401 means the key itself is the problem (re-issue it); 403 means the key is fine but the action isn't allowed (scope, plan, locked account). Neither is fixed by retrying.
• 404 is intentionally ambiguous — BeeL. never confirms the existence of resources your key can't see, to avoid leaking other tenants' data. A 404 for an ID you wrote down may mean wrong environment (sandbox vs live) or wrong key scope.
• The 409 family splits three ways — DUPLICATE_RESOURCE/CLIENT_DUPLICATE/PRODUCT_DUPLICATE (fetch the existing entity), IDEMPOTENCY_KEY_PROCESSING (wait + same key), CONCURRENT_MODIFICATION (refetch, reapply, new key).
• 402/403/429 plan errors are one family — SUBSCRIPTION_*, FEATURE_NOT_AVAILABLE and QUOTA_EXCEEDED all populate details.action (subscribe, update_payment, reactivate_subscription…) so your UI can route the user without parsing messages.

Field-level errors

When validation fails (422), both contracts carry the per-field breakdown:

{
  "type": "https://docs.beel.es/errors/VALIDATION_ERROR",
  "title": "VALIDATION_ERROR",
  "detail": "Los datos proporcionados no son válidos.",
  "instance": "/v1/invoices",
  "errors": [
    { "field": "/recipient", "code": "FIELD_REQUIRED" },
    { "field": "/lines/0/quantity", "code": "LINE_INVALID_QUANTITY" }
  ],
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Los datos proporcionados no son válidos.",
    "details": {
      "recipient": "El campo 'recipient' no puede estar vacío",
      "lines[0].quantity": "La cantidad no puede ser cero ni nula"
    }
  },
  "meta": { "timestamp": "…", "request_id": "…" }
}

errors[] uses RFC 9457 conventions (JSON-pointer-style paths, per-field codes); error.details mirrors the same information as a path → localized message map. Wire errors[].field to your form fields and you get inline validation for free.

Consuming errors programmatically

With the Node.js SDK (@beel_es/sdk), you don't parse anything — typed exception classes inherit from BeeLApiError and expose statusCode, code, requestId, and details:

import { BeeLApiError, BeeLValidationError, BeeLRateLimitError, BeeLConflictError } from '@beel_es/sdk';

try {
  await beel.invoices.create(payload, { idempotencyKey });
} catch (err) {
  if (err instanceof BeeLValidationError) {
    for (const [field, message] of Object.entries(err.details ?? {})) {
      form.setFieldError(field, message); // inline, per-field
    }
  } else if (err instanceof BeeLRateLimitError) {
    await sleep(err.retryAfterSeconds * 1000); // then retry, SAME idempotencyKey
  } else if (err instanceof BeeLConflictError && err.code === 'IDEMPOTENCY_KEY_PROCESSING') {
    await sleep(2000); // then retry, SAME idempotencyKey
  } else if (err instanceof BeeLApiError && err.statusCode >= 500) {
    // retry with SAME idempotencyKey, exponential backoff
  } else {
    throw err; // surface err.message, log err.requestId for support
  }
}

Without the SDK, raw consumption looks like this:

const res = await fetch(`https://app.beel.es/api/v1/invoices/${id}`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

if (!res.ok) {
  const problem = await res.json();
  // Branch on `code`, show `detail` to the user, deep-link docs via `type`.
  throw Object.assign(new Error(problem.detail), {
    code: problem.error.code,
    docsUrl: problem.type,
    traceId: problem.meta.request_id,
    status: res.status,
  });
}

resp = requests.get(
    f"https://app.beel.es/api/v1/invoices/{invoice_id}",
    headers={"Authorization": f"Bearer {api_key}"},
)
if not resp.ok:
    problem = resp.json()
    raise BeelApiError(
        code=problem["error"]["code"],
        message=problem["detail"],
        docs_url=problem["type"],
        trace_id=problem["meta"]["request_id"],
        status=resp.status_code,
    )

# Extract just the code for shell scripting:
curl -s -H "Authorization: Bearer $BEEL_API_KEY" \
     https://app.beel.es/api/v1/invoices/abc-123 \
     | jq -r '.error.code // empty'

# Open the docs page for whatever error you receive:
URL=$(curl -s -H "Authorization: Bearer $BEEL_API_KEY" \
     https://app.beel.es/api/v1/invoices/abc-123 \
     | jq -r '.type // empty')
[ -n "$URL" ] && open "$URL"

Where to go next