오류 및 상태 코드

finlight API는 요청 결과를 알리기 위해 일반적인 HTTP 상태 코드를 사용합니다. 2xx 상태는 성공을, 4xx는 요청이 거부되었음(보통 사용자가 고칠 수 있는 문제)을, 5xx는 당사 측의 문제를 의미합니다. 모든 오류는 무엇이 잘못되었는지 설명하는 JSON 본문을 반환합니다.

참고: REST 및 WebSocket 요청은 X-API-KEY 헤더로 인증합니다. 키가 없거나 유효하지 않으면 401이 반환됩니다. (Webhook 전송 인증 — finlight가 귀하의 엔드포인트로 보내는 헤더 — 은 별개입니다. Webhook 인증을 참조하세요.)

상태 코드 한눈에 보기

400 — Bad Request

쿼리 매개변수나 요청 본문이 검증에 실패하거나, query 문자열이 잘못된 필드 수준 구문을 사용할 때 반환됩니다.

잘못된 매개변수:

{
  "statusCode": 400,
  "message": ["pageSize must not be greater than 100"],
  "error": "Bad Request"
}

잘못된 query 구문(POST /v2/articles):

{
  "statusCode": 400,
  "message": [
    {
      "property": "query",
      "constraints": { "query": "Invalid query syntax near 'ticker:'" }
    }
  ],
  "error": "Bad Request"
}

올바른 query 구문은 고급 쿼리 작성을 참조하세요.

401 — Unauthorized

X-API-KEY 헤더가 없거나 형식이 잘못되었거나 유효한 키가 아닙니다.

{
  "statusCode": 401,
  "message": "Unauthorized"
}

finlight 대시보드에서 키를 받거나 교체하세요.

403 — Forbidden

요청은 인증되었지만 플랜에 요청한 기능이 포함되어 있지 않습니다. 예를 들어, 전체 기사 내용을 포함하지 않는 플랜에서 이를 요청한 경우입니다.

{
  "statusCode": 403,
  "message": "Your subscription does not allow calling the extended article content"
}

각 플랜에 어떤 기능이 포함되는지는 속도 제한 및 할당량을 참조하세요.

404 — Not Found

요청한 리소스가 존재하지 않습니다. 가장 흔한 경우는 finlight가 색인하지 않은 link로 GET /v2/articles/by-link를 호출한 경우입니다.

{
  "statusCode": 404,
  "message": "Article not found"
}

422 — Unprocessable Entity

일부 엔드포인트는 전역 검증기를 통해 검증하며, 필드를 키로 하는 오류 맵을 반환합니다. 각 키는 문제가 된 필드이고, 값은 실패한 제약 조건을 나열합니다.

{
  "status": 422,
  "errors": {
    "language": "language must be a string"
  }
}

참고: 검증 실패는 라우트에 따라 400(기사 엔드포인트) 또는 422(전역 검증기)로 나타날 수 있습니다. 둘 다 잘못된 요청을 의미합니다. 어떤 필드가 실패했는지는 본문을 확인하세요.

429 — Too Many Requests

사용 제한을 초과했습니다. 각각 특정 메시지를 가진 두 가지 다른 경우가 있습니다.

월간 요청 할당량 초과:

{
  "statusCode": 429,
  "message": "Throttling Exception: Exceeded token limit of 5000 for the current period."
}

버스트(단기) 속도 초과:

{
  "statusCode": 429,
  "message": "Throttling Exception: Exceeded rate limit of 10 requests per 10 seconds."
}

참고: finlight는 현재 Retry-After나 속도 제한 헤더를 반환하지 않습니다. 버스트 429의 경우 약 10초 후 백오프하고 재시도하세요. 월간 할당량 429의 경우 다음 청구 주기가 시작될 때(또는 업그레이드 후) 요청이 다시 성공합니다. 속도 제한 및 할당량을 참조하세요.

500 — Internal Server Error

finlight 측에서 예기치 않은 오류가 발생했습니다. 이는 일시적이므로 백오프와 함께 재시도하고, 계속되면 지원을 통해 문의하세요.

{
  "statusCode": 500,
  "message": "Internal server error"
}

오류를 잘 처리하기

• 항상 상태 코드를 먼저 확인한 다음 세부 정보를 위해 JSON 본문을 읽으세요.
• 4xx(429 제외)는 사용자 측 버그입니다. 요청을 수정하세요. 변경 없이 재시도해도 도움이 되지 않습니다.
• 429와 5xx는 재시도할 수 있습니다. 지수 백오프를 사용하세요. 버스트 429의 경우 약 10초면 충분합니다.
• WebSocket 오류는 HTTP 상태가 아니라 소켓의 error 서버 메시지로 도착합니다. WebSocket 기초를 참조하세요.
• Webhook 전송 실패(귀하의 엔드포인트로의)는 동기적으로 반환되지 않고 대시보드에서 추적됩니다. Webhook 테스트를 참조하세요.