Errors

When a request fails, the response has a 4xx or 5xx status and an application/problem+json body:

{
  "type": "https://docs.nowgate.io/errors/amount_too_precise",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "USDC has 6 decimal places; amounts are never rounded.",
  "instance": "/v1/payments",
  "code": "amount_too_precise",
  "request_id": "req_01jc3xb1n6f0q2w8e4r7t5y9v3",
  "errors": [
    {
      "pointer": "/amount",
      "code": "amount_too_precise",
      "detail": "USDC has 6 decimal places; amounts are never rounded."
    }
  ]
}

In the SDKs#

Each SDK turns a problem into an exception of its status's class, carrying the whole problem: status, code, title, detail, type, instance, request_id, retry_after (from Retry-After, in seconds) and errors with their pointers. PHP spells them in camelCase, and the code is errorCode there, since an exception's own code is a number.

try {
  await nowgate.payments.create({ network: "tron", asset: "USDT", amount: "25.0000001" });
} catch (err) {
  if (!(err instanceof InvalidRequestError)) throw err;
  // err.code is "amount_too_precise"; each field's problem has its JSON pointer
  pointer = err.errors[0]?.pointer;
  assert.equal(err.code, "amount_too_precise");
}

try:
    client.payments.create(network="tron", asset="USDT", amount="25.0000001")
except InvalidRequestError as err:
    # err.code is "amount_too_precise"; each field's problem has its JSON pointer
    pointer = err.errors[0]["pointer"]
    check(err.code == "amount_too_precise", err.code)

try {
    $nowgate->payments->create(['network' => 'tron', 'asset' => 'USDT', 'amount' => '25.0000001']);
} catch (InvalidRequestException $e) {
    // $e->errorCode is 'amount_too_precise'; each field's problem has its JSON pointer
    $pointer = $e->errors[0]['pointer'] ?? null;
    check($e->errorCode === 'amount_too_precise', $e->errorCode);
}

An answer that isn't problem JSON, such as a proxy's error page, becomes the exception of its status with the code http_<status> and the first 500 bytes of the body as its detail. The SDKs already retry what may succeed on a retry: see Idempotency and retries.

Retrying#

Most errors fail the same way if you send the same request again. Retry, with the same Idempotency-Key, only after 409, 429 and 5xx errors, and honor Retry-After when present. When 5xx errors go on, status.nowgate.io says whether Nowgate knows of an incident, and when it's resolved.

Rate limits#

When a limit is reached, the API answers 429 with the rate_limited code, and Retry-After gives the seconds to wait. The limits:

A burst is how many requests may arrive at once. After it, requests are allowed at the steady rate. Each key counts on its own, so a busy integration doesn't slow down another one. An IPv6 address counts together with the rest of its /64.

An address that keeps presenting keys that are refused with 401 must wait before any of its keys is checked again, even a valid one, so fix the key rather than retrying it. Spread bulk work over time, and after a 429, wait as long as Retry-After says.

All codes#