Errors

Error Format

Every error uses the same envelope: success: false, an error with a stable code and a human-readable message, and the requestId to quote if you contact support (also sent as the x-request-id header).

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Your balance does not cover this call. Top up at https://apinoa.com/dashboard/balance."
  },
  "requestId": "550e8400e29b41d4a716446655440000"
}

Branch on code, never on message: messages may be reworded, codes do not change within v1. A call that fails is not billed.

Marketplace and SNS API

Your Account

402 is the one to handle: on a prepaid balance it is the normal end of credit, not a fault. Retrying does not clear it.

Your Request

A 400 is never billed.

Backpressure

Both carry a Retry-After header in seconds. Wait that long and retry: it is a real estimate, not a constant. Neither is billed.

Coverage

A 501 is deliberately not a 404 and not an empty list: the data exists, and it could not be read.

Upstream

Retry these with exponential backoff. They are the whole vocabulary: a platform failure is always reported as one of them.

Platform-Wide Errors

These can be returned on any path.

Image Translate

The FONT_* codes belong to custom fonts and are listed in Custom Fonts. Two can come from the translate call itself: FONT_AUTH_REQUIRED (401), when a private font is named without a key that owns it, and FONT_RESOLVE_ERROR (500), when the font could not be loaded.

AliExpress

AliExpress's own error number, when it gave one, is in the body's upstreamCode field and the X-Apinoa-Upstream-Code response header.

Retrying

Retry only what can succeed on a second try: the UPSTREAM_* family, SERVICE_UNAVAILABLE, INTERNAL_ERROR and TOKEN_EXPIRED with exponential backoff, and the 429 codes after their Retry-After. Never retry a 4xx other than 429: it will fail the same way.

const RETRYABLE = new Set(["CAPACITY_SATURATED", "MARKETPLACE_SATURATED", "RATE_LIMITED", "SERVICE_UNAVAILABLE",
  "INTERNAL_ERROR", "TOKEN_EXPIRED", "UPSTREAM_ERROR", "UPSTREAM_READ_FAILED", "UPSTREAM_TIMEOUT", "UPSTREAM_UNAVAILABLE"]);

async function call(url, init = {}, attempts = 4) {
  for (let i = 0; ; i++) {
    const res = await fetch(url, { ...init, headers: { ...init.headers, "x-api-key": process.env.APINOA_API_KEY } });
    const body = await res.json();
    if (body.success) return body.data;
    if (!RETRYABLE.has(body.error.code) || i === attempts - 1) throw new Error(`${body.error.code}: ${body.error.message}`);
    const wait = Number(res.headers.get("retry-after")) || 2 ** i;
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
}