Errors

Every v1 error has the same JSON body. Branch on code, show or log message, and quote request_id when you write to support@fianto.xyz.

The error bodyCopy Anchor Link

{
  "statusCode": 409,
  "error": "Conflict",
  "code": "order_already_paid",
  "message": "That order_id is already paid. Use a new order_id to charge again.",
  "request_id": "req_…",
  "field": "order_id"
}

An unexpected server error always reads internal_error with the message "Something went wrong on our side. Quote the request_id when you contact support."

Request idsCopy Anchor Link

Every response carries an X-Request-Id header: req_ followed by 24 characters. If you send your own X-Request-Id of 8 to 64 letters, digits, _ or -, fianto keeps it, so your logs and fianto's share one id.

CodesCopy Anchor Link

The list of codes is open-ended: fianto can add codes, so treat any code you do not know by its HTTP status. When a response has no specific code, fianto uses a general one for its status, such as bad_request, unauthorized, forbidden, conflict, unprocessable or rate_limited.

The codes you are most likely to meet:

In the SDKCopy Anchor Link

The SDK throws one class per status. Every class extends FiantoError.

The status classes extend APIError. Check a code with isFiantoError(err, ErrorCode.X):

import { APIError, ErrorCode, Fianto, isFiantoError } from '@fianto/sdk';

const fianto = new Fianto();

export async function createCheckout(orderId: string) {
  try {
    return await fianto.checkoutSessions.create({
      mode: 'payment',
      order_id: orderId,
      amount: '12.50',
      description: 'Coffee beans, 1 kg',
      success_url: 'https://shop.example/thank-you',
      cancel_url: 'https://shop.example/cart',
    });
  } catch (err) {
    if (isFiantoError(err, ErrorCode.OrderAlreadyPaid)) {
      return null; // this order is paid; do not charge it again
    }
    if (err instanceof APIError) {
      console.error(err.status, err.code, err.requestId); // quote requestId to support
    }
    throw err;
  }
}

What the SDK retriesCopy Anchor Link

By default the SDK retries a call up to 2 times (maxRetries, 0 to 10). It retries network errors, timeouts, 408, 429, every 5xx, and a 409 only when the code is idempotency_request_in_progress or checkout_unavailable. It never retries any other 4xx, idempotency_key_reused included.

Between attempts it waits for Retry-After when the response sends one, and otherwise backs off from 500 ms, doubling each time up to 8 s, with ±25 % jitter. If Retry-After asks for more than 10 seconds, the SDK does not wait: it throws the error at once. Every retry of a POST reuses the same idempotency key.

instanceof can fail when one app loads the SDK twice, once as ESM and once as CommonJS. isFiantoError works either way.

See alsoCopy Anchor Link