오류 및 할당량

HTTP 상태와 안정적인 기계 판독 가능 코드로 Narwhal 문제를 처리하세요.

REST 오류의 형식: application/problem+json. MCP 도구 오류는 구조화된 콘텐츠에 동일한 문제 필드를 담습니다.

문제 응답

다음 기준으로 분기합니다 status 첫 번째 및 code 순으로 분기하세요. 다음 값: detail —사람이 읽는 진단용 텍스트로 취급하고, 프로그램에서 고정된 값으로 사용하지 마세요.

RFC 9457 문제

{
  "type": "https://narwhalapi.com/problems/series-not-found",
  "title": "Economics series not found",
  "status": 404,
  "detail": "No approved economics observations matched the request.",
  "code": "series_not_found",
  "request_id": "019d1af4-8f33-7b21-91af-ef535f2dcf50"
}

상태 및 코드

상태	공개 코드	의미
`400`	`invalid_query`	국가, 기간 또는 기타 요청 입력이 잘못되었습니다.
`400`	`invalid_cursor`	페이지네이션 커서의 형식이 잘못되었거나 다른 필터에 속합니다.
`400`	`invalid_pair`	from과 to의 통화가 같습니다.
`401`	`invalid_api_key`	Bearer 키가 누락되었거나 형식이 잘못되었거나 알 수 없거나 비활성 상태입니다.
`403`	`plan_upgrade_required`	요청한 이력이 요금제의 조회 기간을 초과합니다. Free는 12개월, Basic은 5년입니다. 이 코드는 유료 시장 기능과 요금제가 허용하는 시점보다 최신인 예측 날짜에도 적용됩니다.
`404`	`series_not_found`	요청과 일치하는 승인된 최신 또는 과거 관측값이 없습니다.
`404`	`resource_not_found`	요청한 명령 리소스를 사용할 수 없습니다.
`404`	`event_not_found`	ID와 일치하는 이벤트가 없습니다.
`404`	`not_found`	ID와 일치하는 캘린더 발표가 없습니다.
`404`	`route_not_found`	요청한 REST 경로가 존재하지 않습니다.
`404`	`tool_not_found`	요청한 MCP 도구가 공개되지 않았거나 존재하지 않습니다.
`404`	`calendar_not_published`	요청한 국가·연도의 캘린더가 게시되지 않았습니다.
`404`	`commodity_not_supported`	이 원자재 코드는 현물 가격 또는 가격 바에 사용할 수 없습니다.
`404`	`currency_not_supported`	이 원자재는 요청한 통화로 표시되지 않습니다.
`404`	`subscription_not_found`	캘린더 구독 ID를 알 수 없거나 본인 소유가 아닙니다.
`404`	`physical_series_not_found`	ID와 일치하는 실물 가격 시계열이 없습니다.
`404`	`palmoil_series_not_found`	ID와 일치하는 팜유 시계열이 없습니다.
`404`	`webhook_request_failed`	웹훅 수신처를 알 수 없거나 해당 전송을 재전송할 수 없습니다.
`405`	`method_not_allowed`	경로는 존재하지만 요청한 HTTP 메서드를 허용하지 않습니다.
`409`	`cursor_expired`	커서가 만료되었거나 스냅샷을 사용할 수 없습니다. 캘린더와 이벤트 커서도 이 오류를 사용합니다. 커서를 빼고 다시 시작하세요.
`409`	`physical_series_ambiguous`	선택 조건이 둘 이상의 시계열과 일치합니다.
`409`	`limit_reached`	요금제의 웹훅 대상 수 제한에 도달했습니다.
`413`	`request_too_large`	요청 본문이 너무 큽니다.
`429`	`rate_limit_exceeded`	네트워크 또는 계정의 단기 구간 한도에 도달했습니다. 재시도 전 대기 시간은 다음 헤더를 따르세요: `Retry-After`.
`429`	`quota_exhausted`	계정이 월간 요청 허용량을 모두 사용했습니다.
`500`	`internal_error`	Narwhal이 요청을 완료하지 못했습니다.
`503`	`api_disabled`	공개 데이터 게이트가 일시적으로 닫혔습니다.
`503`	`economics_unavailable`	Narwhal은 승인된 공식 발표를 바탕으로 요청을 안전하게 처리할 수 없습니다.
`503`	`calendar_coverage_unavailable`	현재 캘린더를 안전하게 제공할 수 없습니다.
`503`	`database_unavailable`	데이터 저장소를 일시적으로 이용할 수 없습니다.
`503`	`rights_state_changing`	Narwhal은 응답을 준비하는 동안 출처 권한이 변경되지 않았음을 확인하지 못했습니다.
`503`	`predictions_unavailable`	현재 예측 데이터를 안전하게 제공할 수 없습니다.
`503`	`upstream_unavailable`	현재 가격 또는 환율 데이터를 읽을 수 없습니다.
`503`	`palmoil_unavailable`	현재 팜유 데이터를 안전하게 제공할 수 없습니다.
`503`	`physical_price_unavailable`	현재 실물 가격 데이터를 안전하게 제공할 수 없습니다.
`503`	`physical_reference_unavailable`	현재 실물 시계열 데이터를 안전하게 제공할 수 없습니다.
`503`	`rate_limiter_unavailable`	Narwhal이 요청 속도 제한을 확인하지 못했습니다. 잠시 후 다시 시도하세요.
`503`	`command_unavailable`	현재 계정 명령을 완료할 수 없습니다.
`503`	`webhook_unavailable`	현재 웹훅을 제공할 수 없습니다.

할당량 헤더

성공한 각 데이터 응답은 할당량을 정확히 1회 소비하며 다음을 포함합니다

X-Request-IDX-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-ResetX-RateLimit-Short-LimitX-RateLimit-Short-RemainingX-RateLimit-Short-Reset

일반 헤더는 5,000건의 요청을 허용하는 UTC 기준 월간 한도를 나타냅니다. 인증된 응답의 단기 구간 헤더가 나타내는 Free 계정 한도: 분당 30건의 요청. 별도의 악용 방지 버킷은 하나의 네트워크 식별자에 대해 분당 120회와 버스트 20회를 허용하므로, 같은 주소를 공유하는 클라이언트는 함께 제한될 수 있습니다. 다음 응답: 429 rate_limit_exceeded 포함합니다 Retry-After —제한을 유발한 단기 구간의 대기 시간입니다. 다음 응답: 429 quota_exhausted 응답은 다음 UTC 기준 캘린더 월이 시작될 때까지 기다려야 합니다. 두 응답 모두 월간 할당량을 소비하지 않습니다.

재시도 동작

재시도 금지 — 400 —요청을 수정하기 전에는 재시도하지 마세요.
재시도 금지 — 401 —거부된 동일한 키로는 재시도하지 마세요.
재시도 429 다음 이후에만 Retry-After 또는 X-RateLimit-Reset.
멱등 요청을 재시도할 수 있는 오류 상태: 500 또는 503 —상한이 있는 지수 백오프와 지터를 적용하여 재시도하세요.
A 404 series_not_found 지원되는 공식 발표가 게시된 후에만 이용할 수 있게 될 수 있습니다.

도움 요청

보낼 정보: 엔드포인트, UTC 시각, 상태, code 및 request_id → Narwhal API 지원. API 키를 절대 포함하지 마세요.

돌아갈 문서: 빠른 시작 ; 검토할 문서: 경제 데이터 API 레퍼런스.