Request tracing & logging

This page is for everyone who calls the e-bon HTTP API — POS partners, accounting integrations, third-party dashboards. It explains the one correlation header you need (X-Request-Id), what every error response looks like, and how to file a bug report we can act on quickly.

Send a request with a trace ID

The X-Request-Id header travels with every request and every response.

A few things to fix in your mental model up front:

• The header is always echoed. There is no opt-out — even health-check responses carry it.
• Headers are case-insensitive on the wire; treat the response header as case-insensitive when reading it.
• We do not validate the inbound value. Pick something sensible: stick to ASCII, keep it under ~256 chars, and prefer UUIDs or your own correlation IDs (e.g. a database PK from your queue table). Do not put PII in the header — it ends up in our logs.
• If you omit the header, we mint a fresh UUID v4. Collisions are not a concern.

Understand why this header matters

Three concrete reasons to care:

1. Bug reports. When you tell us "we got a 500 from POST /api/v1/receipts last Tuesday around 14:30 UTC", we can find that request — in principle — but it takes minutes per call. When you tell us the X-Request-Id, we find it in seconds. See the bug-report checklist below.
2. Correlating client and server logs. Log the X-Request-Id from the response on every non-2xx outcome (and ideally on every call, sampled). When a partner dashboard emits a Sentry event with the request ID attached, your engineers and ours are looking at the same line.
3. Tracing retries. If you re-use the same X-Request-Id on a retry, every attempt shows up in our logs against the same correlation key. This is observability only — re-using the ID does not trigger any deduplication. If you need safe retries with replay, that is the job of Idempotency-Key, a separate header (see the comparison table and the Idempotency reference).

Read the error envelope

Every non-rate-limit error response uses the same JSON shape:

{
  "error": {
    "code": "STRING_CODE",
    "message": "Human-readable explanation",
    "details": "optional, type varies by code"
  }
}

Three branches produce that envelope:

The redaction on the unhandled branch matters: in production the message is always 'An internal error occurred'. The original exception message stays in our server logs, keyed by your X-Request-Id. That is exactly the scenario where you need the header in your bug report.

Skip health-check noise in your logs

The four health endpoints — /health, /ready, /healthz, /livez — do not appear in our access log. They still execute, they still return X-Request-Id, they just don't produce a log line (otherwise Kubernetes liveness/readiness probes would drown the log). See Health & meta for their contracts.

Copy a client recipe

Three short reference clients showing the header round-trip and the bug-report capture pattern. None are production-ready (no retries, no metrics) — they exist to get you started.

import { randomUUID } from 'node:crypto';

async function callWithTrace(url, options = {}) {
  const requestId = randomUUID();
  const headers = { ...(options.headers ?? {}), 'X-Request-Id': requestId };
  const res = await fetch(url, { ...options, headers });
  const echoed = res.headers.get('x-request-id');
  if (!res.ok) {
    const body = await res.json().catch(() => null);
    console.error('[ebon] request failed', {
      method: options.method ?? 'GET',
      url,
      status: res.status,
      sentRequestId: requestId,
      receivedRequestId: echoed,
      errorCode: body?.error?.code ?? body?.code,
    });
  }
  return res;
}

import logging, uuid, requests

log = logging.getLogger('ebon')

def call_with_trace(method, url, **kwargs):
    request_id = str(uuid.uuid4())
    headers = {**kwargs.pop('headers', {}), 'X-Request-Id': request_id}
    r = requests.request(method, url, headers=headers, **kwargs)
    if r.status_code >= 400:
        body = r.json() if r.headers.get('content-type', '').startswith('application/json') else None
        log.error(
            'ebon call failed method=%s url=%s status=%s sent_id=%s recv_id=%s code=%s',
            method, url, r.status_code, request_id,
            r.headers.get('X-Request-Id'),
            (body or {}).get('error', {}).get('code') or (body or {}).get('code'),
        )
    return r

curl -sS -D - -o /tmp/body.json -w '\nHTTP %{http_code}\n' \
  -H "Authorization: Bearer $EBON_KEY" \
  -H "X-Request-Id: $(uuidgen)" \
  -X POST -d @body.json \
  https://api.e-bon.ro/api/v1/receipts \
  | grep -i '^x-request-id:'

# Then, on a failure:
cat /tmp/body.json | jq '.error // .'

File a useful bug report

When something is broken in production, send us this checklist. Half the items are obvious; the request ID is the one that turns a 30-minute investigation into a 30-second one.

For broader debugging context, the Troubleshooting guide covers integration-level failure modes (auth issues, webhook delivery, device pairing) that often manifest as confusing API errors.

Idempotency-Key vs X-Request-Id

The two headers are independent and complementary. Using both on a retry is correct.

The combined recipe for a retry of a fiscal receipt POST: keep the same Idempotency-Key (so the second call replays), keep the same X-Request-Id (so both attempts thread together in our logs), and let the API do the rest.

Continue exploring

• API overview — the front door to the API surface.
• API errors — the full code catalogue and their HTTP status mappings.
• Idempotency — the safe-retry contract; pairs with X-Request-Id on every retry.
• Rate limits — the 429 envelope is FLAT, not the wrapper documented above.
• Health & meta — the four silent paths (/health, /ready, /healthz, /livez).
• Troubleshooting — common integration failure modes.