Handle Gateway Error Responses

When a request to your approved Gateway domain fails, Gateway returns an error response that tells you what failed, what to do next, and whether you can retry. This page shows you how to read that response and how to handle it in your integration. For what each GW_* code means, see the Gateway error code reference.

Gateway error responses follow the RFC 9457 Problem Details standard and use the application/problem+json content type.

What an error response looks like

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json
Cache-Control: no-store
X-Request-ID: 01991d1c-814d-7a62-8c25-9e0a48bf7322

{
  "type": "https://docs.tryduplo.com/invoicing/nrs/errors/GW_API_KEY_INVALID",
  "title": "API key is invalid or expired",
  "status": 401,
  "detail": "The supplied API key could not be authenticated.",
  "instance": "urn:duplo:request:01991d1c-814d-7a62-8c25-9e0a48bf7322",
  "code": "GW_API_KEY_INVALID",
  "requestId": "01991d1c-814d-7a62-8c25-9e0a48bf7322",
  "timestamp": "2026-09-15T12:34:56.789Z",
  "action": {
    "code": "ROTATE_API_KEY",
    "description": "Create or rotate the API key in Duplo Spend, then retry.",
    "documentation": "https://docs.tryduplo.com/invoicing/nrs/errors/GW_API_KEY_INVALID"
  },
  "retry": {
    "strategy": "AFTER_CORRECTION"
  },
  "message": "The supplied API key could not be authenticated.",
  "statusCode": 401,
  "path": "/api/v1/invoice/sign"
}

To handle an error, you need only these fields:

Write your error-handling logic to read code and retry.strategy and decide what to do from those two values. You can show title and detail to users, but never make decisions by matching their English text, because Duplo can reword it at any time.

Handle an error response

Follow these steps whenever a Gateway request fails. In these steps, a mutation is a request that creates or changes something, such as signing, transmitting, onboarding, or QR-material rotation. A read only retrieves data and never changes it.

This function applies steps 1 to 4 and returns the next step for your integration to take:

// Decide the next step after a Gateway request fails.
// `error` is the axios error; `request` describes what you sent.
const decideNextStep = (error, request) => {
  const response = error.response;

  // Step 1: no response, or a response that is not a Gateway error
  if (!response) {
    return {
      next: request.isQrMaterialRotation
        ? "contact-support"
        : "no-gateway-response",
    };
  }
  const contentType = response.headers["content-type"] ?? "";
  if (!contentType.startsWith("application/problem+json")) {
    return { next: "no-gateway-response" };
  }

  const problem = response.data;

  // Step 2: keep the request ID with your own record of the request
  console.error(
    "Gateway error",
    problem.code,
    "request ID:",
    problem.requestId,
  );

  // Step 3: documented exceptions take precedence over retry.strategy
  if (request.isQrMaterialRotation && response.status >= 500) {
    return { next: "contact-support", requestId: problem.requestId };
  }
  if (
    (request.isOnboarding || request.isQrMaterialRotation) &&
    problem.code === "GW_IDEMPOTENCY_CONTENT_CONFLICT"
  ) {
    return { next: "contact-support", requestId: problem.requestId };
  }

  // Step 4: act on the returned strategy
  const { strategy, sameIdempotencyKey, afterSeconds } = problem.retry;
  switch (strategy) {
    case "BACKOFF":
      return {
        next: "retry-with-backoff",
        keepIdempotencyKey: sameIdempotencyKey === true,
        retryAfter: response.headers["retry-after"] ?? afterSeconds,
      };
    case "SAME_IDEMPOTENCY_KEY":
      return { next: "retry-with-backoff", keepIdempotencyKey: true };
    case "AFTER_CORRECTION":
      return {
        next: "correct-request",
        keepIdempotencyKey: sameIdempotencyKey === true,
        violations: problem.errors ?? [],
      };
    case "DO_NOT_RETRY":
      return { next: "stop" };
    default:
      // CONTACT_SUPPORT, POLL_OPERATION, or a strategy your code does not recognize
      return { next: "contact-support", requestId: problem.requestId };
  }
};

Choose a retry action

retry.strategy is always present and has one of these values:

Keep or replace the idempotency key. When retry.sameIdempotencyKey is true, any permitted retry must keep the original idempotency key and send the same request content. When a correction changes a mutation's content, send it as new work with a new key: reusing the original key with different content returns GW_IDEMPOTENCY_CONTENT_CONFLICT. A new Pass-through sign attempt also needs the next x-attempt-number; see Design stable idempotency keys.

Exceptions to the returned strategy

For the following cases, do what this section says, even when retry.strategy says otherwise.

Fix validation failures

When request values are invalid, Gateway returns GW_REQUEST_VALIDATION_FAILED and may include an errors array that lists each problem:

{
  "type": "https://docs.tryduplo.com/invoicing/nrs/errors/GW_REQUEST_VALIDATION_FAILED",
  "title": "Request validation failed",
  "status": 400,
  "detail": "One or more request values are invalid.",
  "instance": "urn:duplo:request:01991d1c-814d-7a62-8c25-9e0a48bf7322",
  "code": "GW_REQUEST_VALIDATION_FAILED",
  "requestId": "01991d1c-814d-7a62-8c25-9e0a48bf7322",
  "timestamp": "2026-09-15T12:34:56.789Z",
  "action": {
    "code": "CORRECT_REQUEST",
    "description": "Correct the listed request values and submit the request again.",
    "documentation": "https://docs.tryduplo.com/invoicing/nrs/errors/GW_REQUEST_VALIDATION_FAILED"
  },
  "retry": {
    "strategy": "AFTER_CORRECTION"
  },
  "errors": [
    {
      "location": "header",
      "field": "x-sub-business-id",
      "code": "FORMAT",
      "detail": "Copy the immutable represented-business ID returned as gatewaySubBusinessId without changing it."
    }
  ],
  "message": "One or more request values are invalid.",
  "statusCode": 400,
  "path": "/api/v1/invoice/sign"
}

Each item in errors has these fields:

Correct every listed problem before retrying. Gateway lists at most 20, so a corrected request can still fail with problems that were not listed the first time. Gateway never returns secret values or raw validator exceptions.

Look up an error code

When you need to know what a specific code means and what to do about it, find it in the Gateway error code reference. Each entry gives the meaning, the required action, and the retry strategy Gateway returns.

Contact Duplo Support

When the documented action does not resolve the problem, send Duplo Support:

• the returned requestId, HTTP status, and code;
• the UTC timestamp, your approved Gateway hostname, and whether you were in test or live state;
• your domain's mode (Pass-through or Stored) and mode version;
• the Duplo invoiceId, IRN, and gatewaySubBusinessId when relevant, plus any operationId;
• the idempotency key and attempt number for a mutation;
• for a sign, whether you observed a wallet movement and any authoritative NRS lookup result; and
• a sanitized response body.

Responses that do not use this format

The GW_* codes cover failures that Gateway creates itself: route validation, authentication, authorization, billing, managed invoice operations, and failures from NRS or internal services that Gateway translates into a code listed in the error code reference.

A supported direct NRS route passes through the NRS status, content type, and body only when NRS succeeds with a 2xx response. When NRS fails, Gateway discards the NRS body and returns a GW_* error instead, so do not rely on NRS error text in your integration.

Failures that happen before a request reaches Gateway, such as TLS, DNS, CDN, or load-balancer errors, never use this format. Handle them as described in Confirm the response is a Gateway error.