Error codes — 4xx, 5xx and vendor-specific

Overview

This document is aimed at engineers integrating with BookNLink connectors and modules. It assumes familiarity with the canonical inventory schema and with signed JWT authentication.

Authentication

Every request must carry a bearer token in the Authorization header. Tokens are signed JWTs; the signing key is rotated every ninety days. Scopes are per-property and per-module.

Endpoints

GET  /v1/workspaces/:ws_id/inventory
POST /v1/workspaces/:ws_id/reservations
GET  /v1/workspaces/:ws_id/journal

Rate limits

Default 30 requests per second per token, burst up to 90 for two seconds. 429 responses include a Retry-After header. Fair-use thresholds and quotas are documented per module.

Errors

All errors follow the RFC 7807 problem+json format. Structured fields: type, title, status, detail, instance, plus a BookNLink-specific trace_id for correlation.

Webhooks

Webhooks are signed with an HMAC-SHA256 header. Idempotency is enforced with a x-bnl-idempotency-key header on every mutation.