Errors

{
  "error": {
    "type": "validation_error",
    "code": "INVALID_FIELD",
    "message": "Validation failed",
    "details": {
      "amount": ["amount must be a positive integer"]
    },
    "request_id": "req_8f3c2a1b9d7e4f60",
    "timestamp": "2026-01-15T12:30:00.000Z"
  }
}

{
  "error": {
    "type": "validation_error",
    "code": "INVALID_FIELD",
    "message": "Validation failed",
    "details": {
      "amount": ["amount must be a positive integer"],
      "currency": ["currency must be a valid ISO 4217 code"]
    },
    "request_id": "req_8f3c2a1b9d7e4f60",
    "timestamp": "2026-01-15T12:30:00.000Z"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "INVALID_CREDENTIALS",
    "message": "Authentication failed",
    "request_id": "req_3a91c0ed7b224f18",
    "timestamp": "2026-01-15T12:30:00.000Z"
  }
}

{
  "error": {
    "type": "authorization_error",
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "This API key does not have the required scope: transactions:write",
    "request_id": "req_77ba2c41e9f04d3a",
    "timestamp": "2026-01-15T12:30:00.000Z"
  }
}

{
  "error": {
    "type": "not_found_error",
    "code": "RESOURCE_NOT_FOUND",
    "message": "Transaction not found",
    "request_id": "req_5e0d8f3a6c124b97",
    "timestamp": "2026-01-15T12:30:00.000Z"
  }
}

{
  "error": {
    "type": "conflict_error",
    "code": "IDEMPOTENCY_KEY_CONFLICT",
    "message": "This idempotency key was already used with a different request body.",
    "request_id": "req_1c47a98f2b6e40d5",
    "timestamp": "2026-01-15T12:30:00.000Z"
  }
}

{
  "error": {
    "type": "business_rule_error",
    "code": "INVALID_STATE_TRANSITION",
    "message": "Cannot capture a transaction that has already been voided.",
    "details": {
      "current_status": "voided",
      "requested_action": "capture"
    },
    "request_id": "req_9b2f6d1a3e8c47f0",
    "timestamp": "2026-01-15T12:30:00.000Z"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Retry after a short delay.",
    "request_id": "req_4d8e1a07f5c9426b",
    "timestamp": "2026-01-15T12:30:00.000Z"
  }
}

{
  "error": {
    "type": "internal_server_error",
    "code": "INTERNAL_ERROR",
    "message": "Internal server error",
    "request_id": "req_a1b2c3d4e5f60718",
    "timestamp": "2026-01-15T12:30:00.000Z"
  }
}

async function tokeflowRequest(url, options, attempt = 0) {
  const MAX_RETRIES = 4;
  const res = await fetch(url, options);

  if (res.ok) {
    return res.json();
  }

  const body = await res.json();
  const { type, code, message, request_id } = body.error;

  // Always log the request_id — it is your support handle.
  console.error(`Tokeflow error ${res.status} ${code}: ${message} (request_id=${request_id})`);

  const isRetryable = res.status === 429 || res.status >= 500;

  if (isRetryable && attempt < MAX_RETRIES) {
    // Exponential backoff with jitter: 0.5s, 1s, 2s, 4s (+/- jitter).
    const delay = Math.pow(2, attempt) * 500 + Math.random() * 250;
    await new Promise((r) => setTimeout(r, delay));
    return tokeflowRequest(url, options, attempt + 1);
  }

  // 4xx (except 429): the request must change. Surface it to the caller.
  const error = new Error(message);
  Object.assign(error, { type, code, request_id, status: res.status });
  throw error;
}

# Inspect the status code and envelope on a failed request.
curl -i https://api.tokeflow.com/api/v1/transactions/tx_does_not_exist \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxxxxxxxxxx"

# HTTP/1.1 404 Not Found
# {
#   "error": {
#     "type": "not_found_error",
#     "code": "RESOURCE_NOT_FOUND",
#     "message": "Transaction not found",
#     "request_id": "req_5e0d8f3a6c124b97",
#     "timestamp": "2026-01-15T12:30:00.000Z"
#   }
# }