오류 레퍼런스
JSON-RPC, Data API, Push Webhook, 콘솔 및 faucet의 오류 코드, 과금 여부와 재시도 안내입니다. eth_getLogs 블록 범위와 Webhook 재전송 오류도 다룹니다.
BlockVectra 서비스의 전체 오류 코드와 기계가 읽을 수 있는 reason 값을 정리한 레퍼런스입니다. 거부된 호출의 과금 여부, 재시도 정책, 백오프 대기 시간 및 AI 에이전트와 자동화 클라이언트의 권장 처리 방법을 확인할 수 있습니다.
기계가 읽을 수 있는 전체 오류 목록은 /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 키를 잃어버린 경우 참고). |
| 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 키 발급. |
| 429 | -32005 | public_pool_busy | 공개 체인 요청 풀이 사용 중입니다. | 아니요 | 예 | Retry-After를 따르거나 수초 대기 후 백오프로 재시도 | 백오프를 적용해 재시도하거나 API 키를 포함해 요청하세요. API 키 발급. |
| 200 | -32601 | method_not_public | 공개 엔드포인트에서 제공하지 않는 메서드입니다. | 아니요 | 아니요 | — | 공개 엔드포인트가 지원하는 메서드를 사용하거나 API 키를 포함해 요청하세요. API 키 발급. |
| 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`)로 입금 주소를 확인하고 온체인으로 충전하세요. 에이전트 충전 가이드를 참고하거나 자격이 있으면 콘솔에서 한도를 초기화하세요. 잔액을 알 수 있으면 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`)로 입금 주소를 확인하고 온체인으로 충전하세요. 에이전트 충전 가이드를 참고하거나 가능한 경우 한도를 초기화하거나 다음 주기의 무료 크레딧을 기다리세요. 잔액을 알 수 있으면 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`)에서 입금 주소를 확인하고 온체인으로 충전하세요. 에이전트 충전 가이드를 참고하거나 자격이 있으면 콘솔에서 한도를 초기화하세요. |
| 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`)에서 입금 주소를 확인하고 온체인으로 충전하세요. 에이전트 충전 가이드를 참고하거나 무료 크레딧이 다시 제공될 때까지 기다리세요. |
| 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`)에서 입금 주소를 확인하고 온체인으로 충전하세요. 에이전트 충전 가이드를 참고하거나 다음 프로모션 주기를 기다리세요. |
| 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 전송 복구 가이드를 참고하세요. 수신 서버 연동은 원본 요청 본문 서명 검증부터 시작하세요. 스테이블코인 결제 예제에서는 이벤트 중복 제거, 트랜잭션 영수증 확인, 누락 구간 백필 및 체인 재구성 대조를 다룹니다. 사용량 측정은 과금 규칙, 연결 기반 구독의 복구는 WebSocket 재연결을 확인하세요.
logs_range_too_large 오류가 발생하면 eth_getLogs 매개변수를 확인하고 블록 범위 제한 및 분할 조회 가이드에 따라 조회 범위를 줄이세요.
Robinhood Chain에서의 파셋 수령 자격 및 공통 오류 코드 처리는 테스트넷 파셋 가이드를 참조하세요.
최종 수정일: