Concepts

Concepts

What every API Gateway integrator needs to master before going to production: authentication, the response envelope, idempotency, retries, problem+json errors, pagination, amounts, deprecations and rate limits.

The gateway is a headless, server-to-server surface: your system (ERP, CRM, core banking system, fintech app, the healthcare provider’s HIS) talks to it over HTTPS with a key, and the gateway authenticates, validates, applies idempotency and limits, and routes to the Compense business engine. These rules are the same across all 13 modules; understand them once and you avoid mistakes in every one.

sequenceDiagram
  autonumber
  participant S as Your system (SDK)
  participant G as API Gateway /v1/gateway
  participant M as Compense engine
  S->>G: POST + X-API-Key + Idempotency-Key
  G->>G: key → tenant + scopes · rate limit
  G->>G: Idempotency-Key already seen?
  alt first time
    G->>M: normalized request
    M-->>G: engine result
    G-->>S: 200 {status, transaction_id, module, data}
  else repeated
    G-->>S: 200 stored response (idempotent_replay: true)
  end
  Note over S,G: Errors: application/problem+json with trace_id (= X-Request-ID)
ConceptIn one sentence
AuthenticationX-API-Key header; the key resolves the tenant and its scopes.
Response envelopeWrites return {status, transaction_id, module, data}; reads return the engine’s body.
IdempotencyEvery write carries an Idempotency-Key; repeating it returns the original response.
Retries and backoffThe SDKs retry 429/502/503/504 with exponential backoff and jitter; writes only if you enable it.
ErrorsRFC 9457 problem+json, one typed exception per code in each SDK.
PaginationPage (page number) and OffsetPage (limit/offset).
AmountsAlways decimal strings ("3500000.00"), never floats.
DeprecationsDeprecation/Sunset headers; the SDKs warn once per operation.
Rate limitsPer-minute limit and monthly quota per key; 429 with Retry-After.

In this section #

Concepts AuthenticationThe X-API-Key header, how the key resolves the tenant and scopes, what 401 and 403 mean, the IP allowlist and signing high-value requests. Concepts Response envelopeWhat the gateway returns: the transaction envelope for writes (status, transaction_id, module, data, idempotent_replay), the engine’s body for reads, and how each … Concepts IdempotencyWhy every write carries an Idempotency-Key, what happens when you repeat it (stored response or 409), how to choose stable keys per business operation, and how the five … Concepts Retries and backoffWhat the SDKs retry on their own (429, 502, 503, 504 with exponential backoff, jitter and Retry-After), why writes aren’t retried by default, and how to enable it … Concepts problem+json errorsThe RFC 9457 format of gateway errors, the table of codes and types, the equivalent exception in each SDK, and how to read validation errors and engine rejections. Concepts PaginationThe gateway’s two list shapes (Page with a page number and OffsetPage with limit/offset) and how to iterate through them fully in Python, JavaScript/TypeScript, … Concepts Amounts as decimal stringsWhy the gateway sends and receives money as decimal strings (MoneyCOP), which types each SDK accepts when sending an amount, and how to read amounts from responses … Concepts Versioning and deprecationsHow the API and the SDKs are versioned (SemVer aligned with /v1), which changes won’t break your integration, and how the SDKs warn you when an operation is about … Concepts Rate limits and quotasEach key’s per-minute limit and monthly quota, the RateLimit-* headers, what to do when you get a 429, and request size limits.