# 오류 레퍼런스

> Source: https://docs.blockvectra.com/ko/errors/

BlockVectra 서비스의 전체 오류 코드와 기계가 읽을 수 있는 `reason` 값을 정리한 레퍼런스입니다. 거부된 호출의 과금 여부, 재시도 정책, 백오프 대기 시간 및 AI 에이전트와 자동화 클라이언트의 권장 처리 방법을 확인할 수 있습니다.

기계가 읽을 수 있는 전체 오류 목록은 [/errors.json](https://docs.blockvectra.com/errors.json)에서 JSON으로 가져올 수 있습니다. 오류 응답의 `docs_url`은 이 페이지의 안정적인 앵커를 가리킵니다: `https://docs.blockvectra.com/en/errors/#<reason>` (`reason` 코드가 없는 오류는 `#-<code-number>` 사용).

### JSON-RPC 오류



| HTTP | 오류 코드 | 원인 코드 | 의미 | 과금 여부 | 재시도 가능 | 대기 시간 (Retry-After) | 에이전트 처리 방법 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 401 | -32024 | `missing_api_key` | API 키가 없습니다. 요청 경로(/v1/{chain}/<api_key>) 또는 x-api-key 헤더로 전달하세요. | 아니요 | 아니요 | — | JSON-RPC 엔드포인트(/v1/{chain})에는 요청 경로(/v1/{chain}/<api_key>) 또는 x-api-key 헤더로 API 키를 전달하세요. Top-up API(/v1/topup/*)에는 x-api-key 헤더로만 전달하세요. |
| 401 | -32024 | `invalid_api_key` | 알 수 없거나 비활성화 또는 폐기된 API 키입니다. JSON-RPC와 Data API 모두 HTTP 401과 invalid_api_key 오류를 반환합니다(JSON-RPC: error.code -32024 및 error.data.reason invalid_api_key; Data API: error.code 및 error.data.reason invalid_api_key). | 아니요 | 아니요 | — | API 키를 확인하세요. 필요하면 콘솔 또는 프로그래밍 방식의 가입으로 다시 로그인하여 새 키를 발급하세요([세션이나 API 키를 잃어버린 경우](https://docs.blockvectra.com/en/guides/programmatic-signup/#lost-your-session-or-api-key) 참고). |
| 403 | -32025 | `key_expired` | API 키가 만료되었습니다. 콘솔에서 새 키를 발급하세요. | 아니요 | 아니요 | — | 콘솔 또는 프로그래밍 방식의 가입으로 새 API 키를 발급하세요. |
| 403 | -32025 | `key_cap_exhausted` | API 키의 CU 한도를 모두 사용했습니다. 콘솔에서 새 키를 발급하세요. | 아니요 | 아니요 | — | 키의 누적 CU 한도를 모두 사용했습니다. 콘솔 또는 프로그래밍 방식의 가입으로 새 키를 발급하세요. |
| 503 | -32021 | `auth_unavailable` | 인증 데이터를 일시적으로 사용할 수 없습니다. | 아니요 | 예 | Retry-After 헤더에 지정된 초만큼 대기 | 서버가 일시적으로 키를 검증할 수 없습니다. 키 자체의 문제가 아닙니다. Retry-After에 지정된 시간만큼 기다린 뒤 재시도하세요. **키를 다시 발급하지 마세요**. |
| 404 | -32600 | `unknown_chain` | 알 수 없는 체인입니다. | 아니요 | 아니요 | — | GET /v1/chains 또는 list_chains 도구로 지원 체인을 확인하고 URL 경로를 확인하세요. |
| 404 | 404 | `unknown_endpoint` | Data API 메서드와 경로가 알려진 작업과 일치하지 않습니다. | 아니요 | 아니요 | — | Data API 문서에 따라 메서드와 URL 경로를 확인하세요. |
| 200 | -32700 | `parse_error` | JSON 파싱 오류입니다. | 아니요 | 아니요 | — | 전송 전에 요청 본문의 JSON 문법을 확인하세요. |
| 200 | -32600 | `invalid_request` | 올바르지 않은 요청입니다. | 아니요 | 아니요 | — | 요청 구조와 jsonrpc: '2.0', id, method 필드를 확인한 뒤 다시 전송하세요. |
| 200 | -32602 | `invalid_params` | 허용되지 않은 tracer입니다. | 아니요 | 아니요 | — | 메서드 매개변수를 수정하고 체인에서 지원하는 tracer와 timeout 한도를 확인하세요. |
| 200 | -32602 | `logs_range_too_large` | eth_getLogs 블록 범위가 너무 큽니다. 최대 <N>개 블록까지 조회할 수 있습니다. | 아니요 | 아니요 | — | GET /v1/chains의 max_logs_block_range 이내로 블록 조회 범위를 줄이세요. |
| 429 | -32005 | `public_rate_limit` | 공개 엔드포인트의 요청 속도 제한을 초과했습니다. | 아니요 | 예 | Retry-After 헤더에 지정된 초만큼 대기 | Retry-After에 지정된 시간만큼 기다린 뒤 재시도하거나 API 키를 포함해 요청하세요. [API 키 발급](https://blockvectra.com/en/get-api-key/?ref=err-public). |
| 429 | -32005 | `public_pool_busy` | 공개 체인 요청 풀이 사용 중입니다. | 아니요 | 예 | Retry-After를 따르거나 수초 대기 후 백오프로 재시도 | 백오프를 적용해 재시도하거나 API 키를 포함해 요청하세요. [API 키 발급](https://blockvectra.com/en/get-api-key/?ref=err-public). |
| 200 | -32601 | `method_not_public` | 공개 엔드포인트에서 제공하지 않는 메서드입니다. | 아니요 | 아니요 | — | 공개 엔드포인트가 지원하는 메서드를 사용하거나 API 키를 포함해 요청하세요. [API 키 발급](https://blockvectra.com/en/get-api-key/?ref=err-public). |
| 200 | -32601 | `method_not_allowed` | 이 체인에서 제공하지 않거나 정책상 비활성화된 메서드입니다. | 아니요 | 아니요 | — | GET /v1/chains의 methods.allow 및 methods.deny로 지원 메서드를 확인하세요. 트랜잭션 전송 지원 여부는 GET /v1/chains의 methods.allow로 결정됩니다. 현재 트랜잭션 전송을 지원하지 않는 체인: HyperEVM. |
| 200 | -32601 | `subscription_not_available` | 이 체인에서는 WebSocket 구독을 제공하지 않습니다. | 아니요 | 아니요 | — | GET /v1/chains에서 해당 체인의 지원 구독을 확인하세요. |
| 200 | -32602 | `logs_filter_required` | logs 구독에는 address 또는 topic0(topics의 첫 번째 위치에 null이 아닌 값)가 필요합니다. | 아니요 | 아니요 | — | logs 필터에 address 또는 null이 아닌 topic0을 지정하세요. |
| 200 | -32600 | `batch_too_large` | 배치가 너무 큽니다. 최대 <N>회 호출까지 가능합니다. | 아니요 | 아니요 | — | 오류 데이터에 표시된 최대 호출 수에 맞게 배치를 나누세요. |
| 413 | 413 | `request_too_large` | Data API 요청 본문이 크기 한도를 초과했습니다. | 아니요 | 아니요 | — | 요청 본문 크기를 줄이세요. |
| 200 | -32000 | `not_found` | 트랜잭션을 찾을 수 없습니다. | 아니요 | 아니요 | — | 방금 전송되거나 블록에 포함된 트랜잭션이라면 전파될 때까지 기다린 뒤 재시도하세요. 그 외에는 블록 번호 또는 해시를 확인하세요. |
| 200 | -32011 | `state_window` | 최근 <N>개 블록 범위 밖의 과거 상태는 조회할 수 없습니다. | 아니요 | 아니요 | — | GET /v1/chains의 state_window_blocks 이내의 블록을 조회하거나 과거 데이터는 Data API를 사용하세요. |
| 200 | -32011 | `range_not_indexed` | 요청한 과거 데이터가 완전히 인덱싱되지 않았습니다. | 아니요 | 아니요 | — | 인덱싱된 범위로 조회 구간을 줄이세요. 데이터가 없는 동일 구간을 그대로 재시도하지 마세요. |
| 200 | -32011 | `history_not_ready` | 요청한 과거 데이터가 아직 준비되지 않았습니다. | 아니요 | 예 | 인덱싱 완료까지 대기; error.data.retry_after_seconds가 있으면 해당 시간 준수 | 인덱싱이 완료된 뒤 재시도하세요. error.data.retry_after_seconds가 있으면 해당 시간만큼 기다리세요. |
| 429 | -32005 | `key_rate_limit` | 속도 제한을 초과했습니다. | 아니요 | 예 | Retry-After 헤더에 지정된 초만큼 대기 | Retry-After에 지정된 시간만큼 기다린 뒤 재시도하거나 부하를 분산하세요. |
| 429 | rate_limited | `rate_limited` | API 또는 GET /v1/account 요청 속도 제한을 초과했습니다(GET /v1/account는 키당 초당 5회 초과). | 아니요 | 예 | Retry-After 헤더에 지정된 초만큼 대기 | Retry-After에 지정된 시간만큼 기다린 뒤 재시도하세요. |
| 429 | -32005 | `concurrency_limit` | 속도 제한을 초과했습니다. | 아니요 | 예 | Retry-After를 따르거나 실행 중인 호출이 완료될 때까지 대기 | 클라이언트의 동시 요청 수를 제한하고 실행 중인 요청이 완료되면 재시도하세요. |
| 429 | -32005 | `free_plan_call_limit` | 속도 제한을 초과했습니다. | 아니요 | 예 | 1초 대기 후 재시도 | 요청 빈도를 줄이거나 잔액을 충전하여 유료 플랜 처리량을 사용하세요. |
| 429 | -32022 | `request_exceeds_burst` | 요청 비용 <N> CU가 버스트 용량 <M> CU를 초과합니다. | 아니요 | 아니요 | — | 기다려도 해결되지 않습니다. 배치를 나누거나 메서드 매개변수를 줄여 버스트 용량 이내로 요청하세요. |
| 429 | -32022 | `free_plan_batch_too_large` | 요청의 <N>회 호출이 무료 플랜의 초당 <M>회 한도를 초과합니다. | 아니요 | 아니요 | — | 기다려도 해결되지 않습니다. 무료 플랜 호출 한도 이내로 배치를 나누거나 잔액을 충전하세요. |
| 429 | -32005 | `ws_connection_limit` | 이 키 또는 계정의 WebSocket 연결 한도에 도달했습니다. | 아니요 | 아니요 | — | 사용하지 않는 WebSocket 연결을 닫거나 기존 연결을 재사용하세요. |
| 200 | -32022 | `subscription_limit` | 이 연결의 WebSocket 구독 한도에 도달했습니다. | 아니요 | 아니요 | — | 기존 구독을 해제하거나 다른 연결을 여세요. |
| 200 | -32005 | `ws_filter_capacity` | WebSocket logs 필터 용량에 도달했습니다. | 아니요 | 아니요 | — | 기존 logs 구독을 해제하거나 필터 범위를 줄이세요. |
| 200 | -32026 | `ws_push_overloaded` | WebSocket 알림 큐가 과부하 상태입니다. | 아니요 | 예 | 백오프로 나중에 재시도하거나 재연결 | 지수 백오프를 적용해 eth_subscribe를 재시도하거나 재연결하세요. 기존 구독은 계속 알림을 받습니다. |
| 200 | -32005 | `overloaded` | 서비스가 과부하 상태입니다. 나중에 재시도하세요. | 아니요 | 예 | 수초 대기 후 지수 백오프로 재시도 | 무작위 지연(jitter)을 포함한 백오프를 적용해 요청을 재시도하세요. |
| 402 | -32020 | `balance_exhausted` | 잔액이 부족합니다. 잔액을 알 수 있으면 error.data에 balance_units 및 balance_cu가 포함됩니다. | 아니요 | 아니요 | — | 콘솔 또는 `GET /v1/topup/deposit-address`(MCP `get_deposit_address`)로 입금 주소를 확인하고 온체인으로 충전하세요. [에이전트 충전 가이드](https://docs.blockvectra.com/en/guides/agent-topup/)를 참고하거나 자격이 있으면 콘솔에서 한도를 초기화하세요. 잔액을 알 수 있으면 error.data에 balance_units(초과 사용 시 음수) 및 balance_cu가 포함됩니다. |
| 402 | -32020 | `free_grant_exhausted` | 무료 크레딧을 모두 사용했습니다. 잔액을 알 수 있으면 error.data에 balance_units 및 balance_cu가 포함됩니다. | 아니요 | 아니요 | — | 콘솔 또는 `GET /v1/topup/deposit-address`(MCP `get_deposit_address`)로 입금 주소를 확인하고 온체인으로 충전하세요. [에이전트 충전 가이드](https://docs.blockvectra.com/en/guides/agent-topup/)를 참고하거나 가능한 경우 한도를 초기화하거나 다음 주기의 무료 크레딧을 기다리세요. 잔액을 알 수 있으면 error.data에 balance_units(초과 사용 시 음수) 및 balance_cu가 포함됩니다. |
| 503 | -32021 | `billing_unavailable` | 과금 데이터를 일시적으로 사용할 수 없습니다. | 아니요 | 예 | Retry-After 헤더에 지정된 초만큼 대기 | 잔액 문제가 아닙니다. 새 API 키는 수초 내에 동기화됩니다. Retry-After에 지정된 시간만큼 기다린 뒤 재시도하세요. |
| 200 | -32010 | `node_syncing` | 노드가 동기화 중이어서 일시적으로 호출할 수 없습니다. | 아니요 | 예 | 수초 대기 후 재시도 | 노드 동기화가 완료될 때까지 기다리거나 GET /v1/status를 확인하세요. |
| 200 | -32603 | `upstream_unavailable` | 상위 서비스를 사용할 수 없습니다. | 아니요 | 예 | 수초 대기 후 재시도 | 지수 백오프를 적용해 재시도하고 GET /v1/status에서 노드 상태를 확인하세요. |
| 504 | 504 | `upstream_timeout` | 상위 서비스가 제한 시간 내에 응답하지 않았습니다. | 아니요 | 예 | 잠시 대기 후 재시도 | 지수 백오프를 적용해 요청을 재시도하세요. |
| 200 | -32000 | `response_too_large` | 상위 서비스의 응답이 너무 큽니다. | 아니요 | 아니요 | — | 조회 매개변수를 줄이세요(예: eth_getLogs 블록 범위를 줄이거나 더 작은 trace 요청). |
| 200 | -32603 | `internal_error` | 서비스 내부 오류입니다. | 아니요 | 아니요 | — | 요청을 재시도하세요. 오류가 지속되면 발생 시각과 함께 지원팀에 문의하세요. |
| 200 | 4444 | — | 정리된 과거 데이터는 조회할 수 없습니다. | 아니요 | 아니요 | — | 블록이 노드의 과거 데이터 보관 범위를 벗어났습니다. 과거 블록은 Data API로 조회하세요. |
| 200 | -32000 | — | 과거 상태가 없거나 데이터 정리로 과거 데이터를 조회할 수 없습니다. | 아니요 | 아니요 | — | 상태 조회 범위 이내의 블록을 조회하거나 과거 데이터는 Data API를 사용하세요. |
| 200 | -32002 | — | 노드의 배치 실행 시간이 초과되었습니다. | 아니요 | 예 | 수초 대기 후 더 작은 배치로 재시도 | 배치의 호출 수를 줄인 뒤 재시도하세요. |
| 200 | -32003 | — | 노드의 배치 응답 본문이 너무 큽니다. | 아니요 | 아니요 | — | 배치를 더 작은 요청으로 나누어 응답 크기를 줄이세요. |
| 200 | -32601 | — | 노드에서 메서드를 사용할 수 없습니다. | 아니요 | 아니요 | — | GET /v1/chains의 methods.allow 및 methods.deny로 지원 메서드를 확인하세요. 트랜잭션 전송 지원 여부는 GET /v1/chains의 methods.allow로 결정됩니다. 현재 트랜잭션 전송을 지원하지 않는 체인: HyperEVM. |
| 200 | -32603 | — | 노드 내부 오류입니다. | 아니요 | 예 | 잠시 대기 후 재시도 | 요청을 재시도하세요. 오류가 지속되면 발생 시각과 함께 지원팀에 문의하세요. |
| 200 | -32600 | — | 노드가 배치 요청 전체를 거부했습니다. | 아니요 | 아니요 | — | 배치 내 각 요청의 매개변수가 올바른지 확인하고 나누어 재시도하세요. |
| 200 | * | — | 노드 실행 오류입니다(예: execution reverted 또는 매개변수 검증 실패). | 예 | 아니요 | — | 노드가 계산을 수행했으므로 과금됩니다. revert 원인과 데이터 또는 호출 매개변수를 확인하세요. 그대로 반복 요청하지 마세요. |
| 408 | 408 | — | 요청 헤더 수신 완료부터 응답까지 35초를 초과했습니다. | 가능성 있음 | 예 | 읽기 호출은 수초 대기 후 재시도 | 호출이 노드에 도달해 과금될 수 있습니다. 읽기 호출은 백오프를 적용해 재시도하세요. 쓰기 호출(예: eth_sendRawTransaction)은 먼저 해시로 트랜잭션 상태를 확인하세요. |

### WebSocket 종료 코드

WebSocket 연결 종료 코드와 권장 클라이언트 처리 방법입니다.

| 오류 코드 | 원인 코드 | 의미 | 재시도 가능 | 대기 시간 (Retry-After) | 에이전트 처리 방법 |
| --- | --- | --- | --- | --- | --- |
| 1001 | — | 유휴 연결입니다. | 예 | 필요하면 재연결 | 필요하면 재연결하세요. |
| 1003 | — | 바이너리 프레임을 허용하지 않습니다. | 아니요 | — | 자동으로 재연결하지 마세요. UTF-8 텍스트 프레임만 전송하세요. |
| 1009 | — | 메시지가 너무 큽니다. | 아니요 | — | 자동으로 재연결하지 마세요. 큰 요청을 나누어 1 MiB 미만으로 전송하세요. |
| 1012 | — | 서비스가 재시작되었습니다. | 예 | jitter를 포함한 백오프로 재연결 | jitter를 포함한 백오프로 재연결하고 구독을 다시 설정한 뒤 누락 데이터를 백필하세요. |
| 1013 | — | 체인을 사용할 수 없거나 과부하 상태입니다. | 예 | 지수 full-jitter 백오프로 재연결 | 지수 full-jitter 백오프로 재연결하고 구독을 다시 설정한 뒤 누락 데이터를 백필하세요. |
| 4402 | — | 잔액이 부족합니다. | 아니요 | — | 자동으로 재연결하지 마세요. 콘솔 또는 `GET /v1/topup/deposit-address`(MCP `get_deposit_address`)에서 입금 주소를 확인하고 온체인으로 충전하세요. [에이전트 충전 가이드](https://docs.blockvectra.com/en/guides/agent-topup/)를 참고하거나 자격이 있으면 콘솔에서 한도를 초기화하세요. |
| 4404 | — | 유효하지 않은 API 키입니다. | 아니요 | — | 자동으로 재연결하지 마세요. 콘솔에서 API 키를 확인하거나 교체하세요. |
| 4408 | — | 푸시 큐가 512 KiB(524,288바이트)를 초과하면 서비스가 세션을 종료하고 대기 알림을 삭제합니다. 종료 프레임을 받지 못할 수 있습니다(브라우저는 1006 표시). 예상치 못한 연결 종료도 4408과 동일하게 처리하세요. | 예 | 백오프로 재연결; 구독을 줄이거나 더 빠르게 읽기 | 종료 프레임 없이 연결이 끊긴 경우(브라우저 1006)도 4408과 동일하게 처리하세요. 백오프로 재연결하고 구독을 복원한 뒤 eth_getLogs로 누락 데이터를 백필하세요. 구독을 줄이거나 데이터를 더 빠르게 읽으세요. |
| 4429 | — | 푸시 속도 제한을 초과했습니다. | 예 | 백오프로 재연결하거나 구독 줄이기 | 구독을 줄이거나 백오프를 적용해 재연결하세요. |
| 4503 | — | 과금 정보를 사용할 수 없습니다. | 예 | 지수 full-jitter 백오프로 재연결 | 지수 full-jitter 백오프로 재연결하고 구독을 다시 설정하세요. |

### Data API 오류

/v1/data/{chain}/의 블록체인 Data API 엔드포인트에서 반환하는 오류입니다.

| HTTP | 오류 코드 | 원인 코드 | 의미 | 과금 여부 | 재시도 가능 | 대기 시간 (Retry-After) | 에이전트 처리 방법 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 400 | bad_request | — | 중복된 쿼리 매개변수, 유효하지 않은 쿼리 문자열 또는 잘못된 요청입니다. | 아니요 | 아니요 | — | limit 등의 매개변수가 한 번만 나오고 쿼리 매개변수가 올바른지 확인하세요. |
| 409 | not_indexed_yet | — | 요청한 블록 번호 또는 구간이 as_of_block보다 뒤에 있거나, 해시에 해당하는 블록이 as_of_block보다 뒤에 있습니다(인덱싱된 블록이 있으면 indexed_through 포함). | 아니요 | 예 | indexed_through가 대상 블록에 도달할 때까지 수초 대기 | 요청 블록 또는 to_block이 indexed_through 이하가 될 때까지 폴링하거나 체인에서 블록 인덱싱이 시작될 때까지 기다리세요. |
| 409 | window_too_large | — | 블록 구간이 100,000개 블록을 초과하며 clamp가 true로 설정되지 않았습니다. | 아니요 | 아니요 | — | from_block부터 to_block까지의 범위를 100,000개 블록 이하로 줄이거나 clamp=true를 전달하세요. |
| 409 | too_many_pools | — | 토큰이 200개를 초과하는 유동성 풀과 연결되어 있습니다. 풀별로 조회하세요. | 아니요 | 아니요 | — | 토큰의 모든 풀을 조회하는 대신 특정 풀 주소로 조회하세요. |
| 409 | span_exceeded | — | 요청한 날짜 구간이 최대 90일을 초과했습니다. | 아니요 | 아니요 | — | from_time과 to_time 사이의 구간을 90일 이내로 줄이세요. |
| 422 | no_coverage | — | 이 체인에서 지원하지 않는 기능이거나 요청 블록이 데이터 범위보다 이전입니다. | 아니요 | 아니요 | — | 조회 전에 GET /v1/data/chains의 `features`와 `coverage.from_block` 또는 무료 GET /v1/status의 `data_features`를 확인하세요. |
| 503 | unavailable | — | 데이터 서비스를 일시적으로 사용할 수 없습니다. | 아니요 | 예 | 수초 대기 후 지수 백오프로 재시도 | 잠시 기다린 뒤 지수 백오프를 적용해 재시도하세요. |
| 402 | insufficient_balance | — | 유료 잔액 또는 무료 크레딧을 모두 사용했습니다. 잔액을 알 수 있으면 error.data에 balance_units 및 balance_cu가 포함됩니다. | 아니요 | 아니요 | — | 콘솔 또는 `GET /v1/topup/deposit-address`(MCP `get_deposit_address`)에서 입금 주소를 확인하고 온체인으로 충전하세요. [에이전트 충전 가이드](https://docs.blockvectra.com/en/guides/agent-topup/)를 참고하거나 무료 크레딧이 다시 제공될 때까지 기다리세요. |
| 429 | cost_exceeds_burst | — | 단일 요청의 비용이 키의 버스트 용량을 초과했습니다. | 아니요 | 아니요 | — | 요청을 더 작게 나누세요. 동일한 요청을 그대로 재시도해도 해결되지 않습니다. |
| 503 | gateway_overloaded | — | Data API 처리 용량을 일시적으로 사용할 수 없습니다. | 아니요 | 예 | Retry-After: 1초 | 계정의 키와 체인 전체에서 동시 요청 수를 줄이고 Retry-After만큼 기다린 뒤 재시도하세요. error.data.reason은 null입니다. |

### 콘솔, 계정 및 faucet API 오류

/v1/의 계정 관리, API 키 발급, 인증 및 faucet 엔드포인트에서 반환하는 오류입니다.

| HTTP | 오류 코드 | 원인 코드 | 의미 | 과금 여부 | 재시도 가능 | 대기 시간 (Retry-After) | 에이전트 처리 방법 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 409 | topup_disabled | — | 충전이 중단되었거나 사용 가능한 충전 네트워크가 없습니다. 새 입금 주소는 할당할 수 없지만 기존 주소는 계정에 유지됩니다. | 아니요 | 아니요 | — | GET /v1/topup/status에서 충전 가능 여부를 확인하고 충전이 활성화된 뒤 재시도하세요. |
| 503 | deposit_unavailable | — | 입금 주소를 일시적으로 할당할 수 없습니다. Retry-After에 따라 재시도하세요. | 아니요 | 예 | Retry-After에 지정된 초만큼 대기하고 지수 백오프 적용 | Retry-After에 지정된 시간과 지수 백오프를 적용해 재시도하세요. |
| 400 | invalid_request | `invalid_username` | 사용자 이름 형식이 올바르지 않습니다(영문자, 숫자 또는 밑줄만 허용). | 아니요 | 아니요 | — | 사용자 이름의 문자 및 길이 요구 사항을 충족하는 이름을 입력하세요. |
| 400 | invalid_request | `expires_at` | 키 만료 시간이 미래가 아니거나 허용된 최대 유효 기간을 초과했습니다. | 아니요 | 아니요 | — | expires_at을 허용 기간(기본 365일) 이내의 미래 RFC 3339 시각으로 설정하거나 expires_in_secs를 사용하세요. |
| 400 | invalid_request | `cu_cap` | cu_cap이 허용 범위 밖입니다(1부터 9007199254740991까지의 정수). | 아니요 | 아니요 | — | cu_cap을 1부터 9007199254740991까지의 정수로 설정하거나 CU를 제한하지 않으려면 생략하세요. |
| 400 | siwe_invalid | `expired` | Sign-In with Ethereum (SIWE) 메시지가 만료되었거나 nonce를 이미 사용했습니다. | 아니요 | 예 | 즉시 새 challenge를 받아 서명 | /v1/auth/siwe/challenge에서 새 challenge를 요청하고 새 메시지에 서명하세요. |
| 400 | siwe_invalid | `chain_mismatch` | SIWE 메시지의 chainId가 서버 설정과 일치하지 않습니다. | 아니요 | 아니요 | — | SIWE 메시지를 만들 때 /v1/auth/siwe/challenge에서 반환한 chainId를 사용하세요. |
| 400 | siwe_invalid | `domain_mismatch` | SIWE 메시지의 domain이 서버 호스트와 일치하지 않습니다. | 아니요 | 아니요 | — | domain과 uri가 challenge에 반환된 서버 호스트와 일치하는지 확인하세요. |
| 400 | siwe_invalid | `signature` | SIWE 서명 검증에 실패했습니다. | 아니요 | 아니요 | — | 지정한 주소에 해당하는 개인 키로 메시지에 서명했는지 확인하세요. |
| 409 | key_limit_reached | `active_keys` | 활성 상태(폐기되지 않은)의 API 키 수가 계정 한도에 도달했습니다. | 아니요 | 아니요 | — | 사용하지 않는 기존 키를 폐기한 뒤 새 키를 발급하세요. |
| 409 | no_reset_available | `nothing_to_reset` | 잔액이 이미 초기화 목표 이상입니다. 초기화 기회는 유지됩니다. | 아니요 | 아니요 | — | 지금은 초기화가 필요하지 않습니다. 잔액을 사용한 뒤 초기화 기회를 사용하세요. |
| 429 | rate_limited | `daily_creations` | 계정의 24시간 API 키 생성 한도에 도달했습니다. | 아니요 | 예 | Retry-After 헤더에 지정된 초만큼 대기 | 새 키를 발급하는 대신 기존 키를 교체하거나 24시간 제한 구간이 갱신될 때까지 기다리세요. |
| 429 | signup_rate_limited | `per_ip` | 클라이언트 IP 서브넷의 가입 속도 제한에 도달했습니다. | 아니요 | 예 | Retry-After 헤더에 지정된 초만큼 대기 | 이 네트워크에서 새 계정을 생성하기 전에 Retry-After에 지정된 시간만큼 기다리세요. |
| 429 | signup_rate_limited | `global` | 모든 경로를 합산한 신규 가입 속도 제한에 도달했습니다. | 아니요 | 예 | Retry-After 헤더에 지정된 초만큼 대기 | Retry-After에 지정된 시간만큼 기다린 뒤 계정 생성을 재시도하세요. |
| 400 | oauth_invalid | — | OAuth 매개변수가 유효하지 않거나 callback state를 알 수 없거나 만료 또는 이미 사용된 상태입니다. | 아니요 | 예 | — | /v1/auth/{provider}/start에서 새 OAuth 로그인 흐름을 시작하세요. |
| 400 | login_code_invalid | — | 로그인 코드를 알 수 없거나 만료 또는 이미 사용되었거나 PKCE verifier가 일치하지 않습니다. | 아니요 | 아니요 | — | 로그인을 다시 시작해 새 로그인 코드를 받으세요. |
| 401 | unauthenticated | — | 세션이 없거나 토큰이 유효하지 않거나 만료 또는 폐기되었습니다. Top-up API(/v1/topup/*)에서는 x-api-key 대신 Authorization에 Bearer가 아닌 값이나 유효하지 않은 토큰을 전달해도 발생합니다. | 아니요 | 아니요 | — | 다시 로그인해 새 Bearer 세션 토큰을 받으세요. Top-up API에 API 키를 전달할 때는 Authorization 대신 x-api-key 요청 헤더를 사용하세요. |
| 403 | user_disabled | — | 관리자가 계정을 정지했습니다. | 아니요 | 아니요 | — | 계정 지원은 contact@blockvectra.com으로 문의하세요. |
| 404 | provider_disabled | — | 알려진 OAuth 제공자이지만 현재 비활성화되어 있습니다. | 아니요 | 아니요 | — | SIWE 또는 지원되는 다른 인증 제공자를 사용하세요. |
| 409 | identity_in_use | — | 지갑 또는 OAuth 계정이 이미 다른 사용자와 연결되어 있습니다. | 아니요 | 아니요 | — | 이전 계정에서 해당 인증 수단의 연결을 해제하거나 다른 인증 수단을 사용하세요. |
| 409 | identity_limit_reached | — | 이 계정의 연결된 인증 수단 수가 최대 5개에 도달했습니다. | 아니요 | 아니요 | — | 불필요한 인증 수단을 해제한 뒤 새 인증 수단을 연결하세요. |
| 409 | last_identity | — | 계정에 남은 유일한 인증 수단은 해제할 수 없습니다. | 아니요 | 아니요 | — | 다른 인증 수단을 먼저 연결한 뒤 해제하세요. |
| 409 | key_not_active | — | 비활성화, 폐기 또는 만료된 API 키를 교체하려 했습니다. | 아니요 | 아니요 | — | 새 키를 발급하거나 활성 키를 교체하세요. |
| 409 | no_reset_available | — | 계정에 남은 한도 초기화 기회가 없습니다. | 아니요 | 아니요 | — | 콘솔 또는 `GET /v1/topup/deposit-address`(MCP `get_deposit_address`)에서 입금 주소를 확인하고 온체인으로 충전하세요. [에이전트 충전 가이드](https://docs.blockvectra.com/en/guides/agent-topup/)를 참고하거나 다음 프로모션 주기를 기다리세요. |
| 413 | payload_too_large | — | 요청 본문이 64 KiB 한도를 초과했습니다. | 아니요 | 아니요 | — | 요청 본문 크기를 64 KiB 미만으로 줄이세요. |
| 503 | signup_paused | — | 신규 가입이 일시 중단되었습니다. 기존 사용자의 로그인은 영향을 받지 않습니다. | 아니요 | 예 | 나중에 가입 재시도 | 상태를 확인하고 나중에 가입을 재시도하세요. |
| 503 | usage_unavailable | — | 사용량 보고 서비스를 일시적으로 사용할 수 없습니다. | 아니요 | 예 | 수초 대기 후 재시도 | /usage 엔드포인트에만 영향을 줍니다. 다른 엔드포인트는 정상 작동합니다. 잠시 후 재시도하세요. |
| 500 | internal | — | 예상치 못한 서버 오류입니다. | 아니요 | 예 | 잠시 대기 후 재시도 | 지수 백오프를 적용해 요청을 재시도하세요. |
| 400 | invalid_address | `invalid_address` | 수신 주소의 형식 또는 체크섬이 올바르지 않습니다. | 아니요 | 아니요 | — | 0x 뒤에 40자리 16진수 문자를 사용하세요. 소문자 또는 EIP-55 체크섬 형식이어야 합니다. data.field(/address)를 확인하세요. |
| 503 | faucet_empty | `faucet_empty` | faucet에 지급액과 트랜잭션 수수료를 충당할 잔액이 부족합니다. | 아니요 | 예 | Retry-After 헤더에 지정된 초만큼 대기 | Retry-After만큼 기다린 뒤 재시도하세요. 수락된 응답 없이 테스트 ETH가 전송되었다고 판단하지 마세요. |
| 503 | service_unavailable | `service_unavailable` | faucet 수령 처리를 일시적으로 사용할 수 없거나 이전 수령 요청의 영수증이 아직 없습니다. | 아니요 | 예 | Retry-After 헤더에 지정된 초만큼 대기 | Retry-After만큼 기다린 뒤 재시도하세요. 수락된 응답 없이 테스트 ETH가 전송되었다고 판단하지 마세요. |

### Push API 오류

/v1/push/의 Webhook 구독 관리 및 이벤트 내역 API에서 반환하는 오류입니다.

| HTTP | 오류 코드 | 원인 코드 | 의미 | 과금 여부 | 재시도 가능 | 대기 시간 (Retry-After) | 에이전트 처리 방법 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 400 | invalid_request | — | 요청 필드, 주소, 페이지 매개변수 또는 블록 범위가 올바르지 않습니다. | 아니요 | 아니요 | — | data.field와 data.invalid를 확인하고 요청을 수정하세요. |
| 401 | missing_api_key | — | x-api-key가 없습니다. | 아니요 | 아니요 | — | x-api-key로 API 키를 전달하세요. |
| 401 | invalid_api_key | — | 알 수 없거나 비활성화 또는 폐기된 API 키입니다. | 아니요 | 아니요 | — | 계정의 활성 키를 사용하세요. |
| 402 | insufficient_balance | — | 이벤트 내역 조회에 사용할 잔액 또는 무료 크레딧을 모두 사용했습니다. | 아니요 | 아니요 | — | data.reason(balance_exhausted 또는 free_grant_exhausted)과 제공되는 data.balance_units / data.balance_cu를 확인하세요. data.topup_url 또는 data.deposit_address_url을 통해 충전하세요. |
| 403 | key_cap_exhausted | — | 이벤트 내역 조회용 API 키의 CU 한도를 모두 사용했습니다. | 아니요 | 아니요 | — | data.cu_cap을 확인하고 콘솔에서 새 키를 발급하세요. |
| 403 | key_expired | — | API 키가 만료되었습니다. | 아니요 | 아니요 | — | 계정의 만료되지 않은 키를 사용하세요. |
| 404 | not_found | — | 경로, 메서드 또는 구독을 찾을 수 없습니다. | 아니요 | 아니요 | — | 경로, 메서드 및 구독 소유권을 확인하세요. |
| 409 | limit_reached | — | 계정의 구독 또는 주소-체인 쌍 한도에 도달했습니다. | 아니요 | 아니요 | — | data.limit와 data.max를 확인하고 구독 또는 주소 수를 줄이세요. |
| 413 | request_too_large | — | 요청 본문이 해당 경로의 크기 한도를 초과했습니다. | 아니요 | 아니요 | — | 주소 배치를 나누거나 본문 크기를 줄이세요. |
| 422 | chain_not_available | — | 푸시를 사용할 수 없는 체인이거나 구독에 포함되지 않은 체인입니다. | 아니요 | 아니요 | — | GET /v1/push/chains와 구독의 체인 목록을 확인하세요. |
| 422 | chains_required | — | 체인을 하나 이상 지정해야 합니다. | 아니요 | 아니요 | — | 비어 있지 않은 chains 객체를 전달하세요. 수신을 중단하려면 offline 상태를 사용하세요. |
| 422 | confirmations_out_of_range | — | 확인 블록 수가 체인의 허용 범위 밖입니다. | 아니요 | 아니요 | — | data.min과 data.max 이내의 confirmations를 선택하세요. |
| 422 | destination_not_allowed | — | 허용되지 않은 수신 URL입니다. | 아니요 | 아니요 | — | data.rule을 확인하세요. userinfo와 fragment가 없는 HTTPS 호스트 이름과 포트 443을 사용하세요. |
| 422 | block_out_of_range | — | 블록 구간이 재전송 또는 내역 조회 가능 범위를 벗어났습니다. | 아니요 | 아니요 | — | data.min_block과 data.max_block에 맞게 범위를 조정하세요. |
| 429 | cost_exceeds_burst | — | 내역 조회 요청 비용이 키의 버스트 용량을 초과했습니다. | 아니요 | 아니요 | — | data.reason(request_exceeds_burst)과 data.max를 확인하고 버스트 용량을 늘린 뒤 재시도하세요. 같은 요청을 그대로 재시도해도 해결되지 않습니다. |
| 429 | rate_limited | — | 관리 또는 내역 조회 속도 제한에 도달했습니다. | 아니요 | 예 | Retry-After에 지정된 초만큼 대기 | 내역 조회라면 data.reason(key_rate_limit 또는 free_plan_call_limit)을 확인하세요. Retry-After에 지정된 초만큼 기다리고 요청 빈도 또는 동시 요청 수를 줄이세요. |
| 500 | internal_error | — | 예상치 못한 서비스 오류입니다. | 아니요 | 아니요 | — | x-request-id를 보관하고 지원팀에 문의하세요. |
| 503 | auth_unavailable | — | API 키 검증을 일시적으로 사용할 수 없습니다. | 아니요 | 예 | Retry-After에 지정된 초만큼 대기 | Retry-After에 지정된 초만큼 기다린 뒤 재시도하세요. |
| 503 | billing_unavailable | — | 내역 조회의 과금 상태를 일시적으로 사용할 수 없습니다. | 아니요 | 예 | Retry-After에 지정된 초만큼 대기 | Retry-After에 지정된 초만큼 기다린 뒤 재시도하세요. |
| 503 | upstream_unavailable | — | 푸시 서비스에 일시적으로 연결할 수 없습니다. | 아니요 | 예 | Retry-After에 지정된 초만큼 대기 | Retry-After에 지정된 초만큼 기다린 뒤 재시도하세요. |
| 503 | service_unavailable | — | 푸시 서비스 또는 주소 처리 용량을 일시적으로 사용할 수 없습니다. | 아니요 | 예 | Retry-After에 지정된 초만큼 대기 | Retry-After에 지정된 초만큼 기다린 뒤 재시도하세요. |

Webhook 구독 또는 재전송 오류는 [Push 전송 복구 가이드](https://docs.blockvectra.com/en/guides/webhook-push/#delivery-retries-and-replay)를 참고하세요. 수신 서버 연동은 [원본 요청 본문 서명 검증](https://docs.blockvectra.com/en/guides/webhook-push/#verify-signatures)부터 시작하세요. [스테이블코인 결제 예제](https://docs.blockvectra.com/en/guides/stablecoin-payments/#receive-payments-with-webhooks)에서는 이벤트 중복 제거, 트랜잭션 영수증 확인, 누락 구간 백필 및 체인 재구성 대조를 다룹니다. 사용량 측정은 [과금 규칙](https://docs.blockvectra.com/en/guides/billing-rules/#webhook-push-billing), 연결 기반 구독의 복구는 [WebSocket 재연결](https://docs.blockvectra.com/en/guides/websocket-subscriptions/#reconnection-and-exponential-backoff)을 확인하세요.

`logs_range_too_large` 오류가 발생하면 [eth\_getLogs 매개변수](https://docs.blockvectra.com/en/api/json-rpc/methods/eth_getLogs/)를 확인하고 [블록 범위 제한 및 분할 조회 가이드](https://docs.blockvectra.com/en/guides/getlogs-block-range/)에 따라 조회 범위를 줄이세요.

Robinhood Chain에서의 파셋 수령 자격 및 공통 오류 코드 처리는 [테스트넷 파셋 가이드](https://docs.blockvectra.com/en/guides/robinhood-testnet-faucet/)를 참조하세요.