Errors

Error handling is part of the API contract. A production integration should branch on machine-readable status and error fields, preserve request ids, retry only when the failure is retryable, and use idempotency keys for state-changing writes.

Error envelope

Examples in the source use a common error shape:

{
  "type": "invalid_request",
  "code": "invalid_request",
  "message": "Example validation or state error using fake data.",
  "request_id": "req_test_000000000123",
  "doc_url": null,
  "statusCode": 400
}

Treat code, type, statusCode, and request_id as integration signals. Do not build business logic by parsing the free-form message. Every response also carries an X-Request-Id header that mirrors request_id; capture it from headers even when there is no JSON body to parse.

Status classes

Error types

type is a fixed, machine-readable classification of the failure. Branch on it for broad handling, and on code for specific cases.

0Pools 403 denial codes

When a 0Pools request is rejected for access reasons, branch on the code field. The message is free-form and may change; the code is stable.

Idempotent retry pattern

const idempotencyKey = order.storedIdempotencyKey;

const response = await fetch(`${process.env.OBIT_GATE_BASE_URL}/gate_sessions`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.OBIT_GATE_SECRET_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': idempotencyKey,
  },
  body: JSON.stringify({
    amount: '100.00',
    currency: 'EUR',
    return_url: 'https://partner.example/complete',
  }),
});

If the network fails after the server created state, retry with the same key. A new key may create a duplicate logical write.

Failure handling table

Operational rules

• Persist request ids in logs.
• Persist idempotency keys for writes.
• Persist event ids for webhooks.
• Use decimal strings for money-like values where the API expects strings.
• Do not depend on undocumented fields.
• Use fake values in docs, tests, and screenshots.
• Keep secrets, PII, provider payloads, and internal runbooks out of public docs and logs.

Related pages