에러

에러 형식

모든 에러는 같은 봉투를 씁니다. success: false, 바뀌지 않는 code와 사람이 읽는 message를 담은 error, 그리고 고객 지원에 문의할 때 알려 줄 requestId(x-request-id 헤더로도 보냅니다)입니다.

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

분기는 message가 아니라 code로 하세요. 메시지는 문구가 바뀔 수 있지만, 코드는 v1 안에서 바뀌지 않습니다. 실패한 호출은 과금되지 않습니다.

Marketplace API와 SNS API

계정

처리해야 할 것은 402입니다. 선불 잔액에서는 결함이 아니라 크레딧이 정상적으로 소진된 것입니다. 다시 시도해도 해결되지 않습니다.

요청

400은 과금되지 않습니다.

백프레셔

둘 다 초 단위의 Retry-After 헤더를 담습니다. 그만큼 기다린 뒤 다시 시도하세요. 고정값이 아니라 실제 추정치입니다. 둘 다 과금되지 않습니다.

지원 범위

501은 일부러 404나 빈 목록으로 응답하지 않는 것입니다. 데이터는 있지만 읽을 수 없었다는 뜻입니다.

업스트림

이 코드들은 지수 백오프로 다시 시도하세요. 이것이 전부입니다. 플랫폼 장애는 항상 이 중 하나로 보고됩니다.

플랫폼 공통 에러

어느 경로에서든 돌아올 수 있습니다.

Image Translate

FONT_* 코드는 맞춤 폰트에 속하며 Custom Fonts에 정리되어 있습니다. 그중 두 개는 번역 호출 자체에서도 돌아올 수 있습니다. 비공개 폰트를 그 폰트를 소유한 키 없이 지정하면 FONT_AUTH_REQUIRED(401), 폰트를 불러올 수 없으면 FONT_RESOLVE_ERROR(500)입니다.

AliExpress

AliExpress가 자체 에러 번호를 준 경우, 본문의 upstreamCode 필드와 X-Apinoa-Upstream-Code 응답 헤더에 담깁니다.

재시도

다시 시도해서 성공할 수 있는 것만 재시도하세요. UPSTREAM_* 계열, SERVICE_UNAVAILABLE, INTERNAL_ERROR, TOKEN_EXPIRED는 지수 백오프로, 429 코드는 Retry-After만큼 기다린 뒤 재시도합니다. 429 이외의 4xx는 재시도하지 마세요. 똑같이 실패합니다.

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));
  }
}