> For the complete documentation index, see [llms.txt](https://docs.nexus.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexus.xyz/api-reference/ko/guides/errors.md). # 오류 계약이 선언하는 상태 코드, 요청 한도 헤더, 그리고 401이 아무것도 알려 주지 않는 이유를 설명합니다. 생성된 모든 엔드포인트 페이지는 해당 작업이 선언하는 상태 코드를 나열합니다. 이 페이지는 API 전반에서 각 코드가 무엇을 의미하는지, 그리고 계약이 의도적으로 거의 알려 주지 않는 두 가지 지점을 설명합니다. ## 오류 모델 | 상태 | 의미 | 참고 | | ----- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `200` | 성공 | 123개 작업 | | `201` | 생성됨 | 5개 작업. `POST /orders`와 `POST /orders/batch` 및 각각의 `/api/v1` 쌍둥이 경로, 그리고 `POST /api/v1/bridge/withdrawals`. | | `101` | 프로토콜 전환 | 두 개의 WebSocket 업그레이드 경로 | | `400` | 유효성 검사 오류 | 50개 작업. 계약이 정의하는 경우 본문에 기계 판독용 `code`가 담깁니다(예: `invalid_window`, `bad_wallet`, `bad_agent`, `expiry_out_of_range`, `invalid_json`). 주문 거부에는 증거금 부족, 유효하지 않은 호가 단위, 수정할 수 없는 주문, 증거금 위반이 포함됩니다. | | `401` | 인증 실패 | 89개 작업. **정보 유출을 막기 위해 모든 401 응답은 의도적으로 동일한 불투명 본문 `{"code":"unauthorized"}`를 반환합니다.** 401은 *이유*를 알려 주지 않습니다. 잘못된 키, 잘못된 서명, 오래된 타임스탬프, 만료된 세션이 모두 똑같이 보입니다. 먼저 시계 오차를 확인하십시오. | | `403` | 금지됨 | 25개 작업. 주문, 펀딩, 레버리지, 증거금, 브리지 출금 쓰기 작업에 대한 관할권 통제 거부로, 호출자의 출처에 대해 영구적이므로 재시도하지 마십시오. 관리자 엔드포인트(관리자 시크릿 필요). 운영자가 크레딧 지급을 동결한 경우의 `POST /account/credit`(`credits_frozen`). `GET /account/deposit-target`의 `EARLY_ACCESS_REQUIRED`. `POST /withdrawals`의 출금 거부. `/transfers` 작업의 `TRANSFER_ACCOUNT_INELIGIBLE` 또는 `TRANSFER_OUTFLOW_BLOCKED`. | | `404` | 찾을 수 없음 또는 사용자 소유가 아님 | 26개 작업. 소유권 확인 실패는 403이 아니라 404를 반환하므로, 다른 계정의 리소스를 탐색할 수 없습니다. | | `409` | 충돌 | 7개 작업. 에이전트 등록의 `duplicate_agent`. 주문 제출 시, 더 이상 대기 중이 아닌 주문이 이미 사용한 `client_id`. 주문 수정 시의 시장 수명 주기 승인 게이트. `POST /api/v1/bridge/withdrawals`에서 다른 금액으로 재사용된 `Idempotency-Key`. `POST /transfers`의 `TRANSFER_ID_CONFLICT`. | | `422` | 처리할 수 없음 | 1개 작업. 의미상 유효하지 않은 데이터, 알 수 없는 필드, 또는 `cross`나 `isolated`가 아닌 `margin_mode`를 담은 `POST /account/margin-mode`. 형식이 잘못된 JSON은 `400`입니다. | | `426` | 업그레이드 필요 | 1개 작업. 검증된 서비스 키가 크레딧을 받을 계정을 `X-Account-Id` 헤더로 보낸 경우의 `POST /account/deposit`. 대신 서명된 본문에 `account_id`를 보내십시오. | | `429` | 요청 한도 초과 | 74개 작업. 아래를 참조하십시오. | | `500` | 내부 오류 | 3개 작업. 세션 저장소 쓰기가 실패한 경우 `POST /auth/login`의 `INTERNAL_ERROR`, 그리고 `GET` 및 `POST /account/margin-mode`의 예기치 않은 내부 오류. | | `502` | 업스트림 사용 불가 | 14개 작업. `/account/summary`와 `/account/state` 및 각각의 `/api/v1` 쌍둥이 경로에서는 `authoritative_margin_unavailable`: 엔진 기준의 증거금 뷰를 일시적으로 사용할 수 없습니다. 이 뷰에서 잔액을 도출하는 엔드포인트는 **실패 시 차단**(fail closed) 방식으로 동작하며, 로컬에서 추정한 잠재적으로 안전하지 않은 수치 대신 오류를 반환합니다. 일시적인 오류이므로 잠시 후 재시도하십시오. 나머지는 추천 조회의 `BAD_GATEWAY`, 펀딩 스냅숏의 `FUNDING_SOURCE_*`, `POST /api/v1/bridge/withdrawals`의 다운스트림 단계 실패, `/transfers` 작업의 `TRANSFER_*` 결과입니다. | | `503` | 서비스 사용 불가 | 11개 작업. `GET /account/deposit-target`의 `DEPOSIT_TARGET_MISCONFIGURED`, 추천 조회의 `REFERRAL_STORE_NOT_CONFIGURED`, `/transfers` 작업의 `TRANSFERS_UNAVAILABLE`, `POST /api/v1/bridge/withdrawals`에서 출금을 사용할 수 없는 경우, 그리고 `POST /account/margin`에서 증거금 조정을 영구적으로 기록할 수 없는 경우. | 작업은 `openapi.json`의 경로 하나와 메서드 하나이며, 각 `/api/v1` 쌍둥이 경로는 별도로 셉니다. 개수는 해당 상태를 선언하는 작업의 수입니다. 다시 계산하려면 저장소 루트에서 다음을 실행하십시오. ```bash python3 -c 'import json, collections; d = json.load(open("eng/apps/exchange/api/openapi.json")); print(sorted(collections.Counter(code for item in d["paths"].values() for method, op in item.items() if method in ("get", "put", "post", "delete", "patch") for code in op.get("responses", {})).items()))' ``` ### 429와 요청 한도 헤더 `429` 본문은 `{"code":"RateLimitExceeded","tier":"Pro"}` 형태이며, 응답에는 다음 헤더가 포함됩니다. | 헤더 | 의미 | | ----------------------- | -------------------- | | `X-RateLimit-Limit` | 사용자 등급에 허용되는 초당 요청 수 | | `X-RateLimit-Remaining` | 현재 구간에 남은 요청 수 | | `X-RateLimit-Reset` | 한도가 재설정되는 Unix 타임스탬프 | | `Retry-After` | 재시도 전 대기할 시간(초) | 무작정 재시도하지 말고 `X-RateLimit-*` 헤더에 맞춰 속도를 조절하십시오. 두 엔드포인트는 `429`를 요청 한도와 무관한 의미로 재사용합니다. `POST /account/credit`(일일 크레딧 한도 소진, UTC 자정에 재설정)와 `POST /faucet`(대기 시간 미경과 또는 누적 상한 도달)입니다. 등급별 상한과 연결 상한은 [요청 한도](https://docs.nexus.xyz/exchange/apis-and-rates/rate-limits)를 참조하십시오. ## CCXT 호환성 ### API 버전 지원 버전 식별자는 이 계약의 릴리스된 사양 태그입니다. 엣지는 자신이 받아들이는 버전을 `/metadata`에 게시합니다. `/metadata`는 엣지가 제공하며 이 계약의 작업이 **아닙니다**. 이 엔드포인트는 `current_api_version`(제공되는 최신 태그)과 `min_api_version`(아직 받아들이는 가장 오래된 태그)을 반환하므로, 클라이언트와 에이전트가 지원 기간을 프로그래밍 방식으로 읽을 수 있습니다. 1.0 이전(`v0.x.y`)에는 호환성이 깨지는 변경이 잦으며, `min_api_version`은 호환성이 깨지는 릴리스마다 상향될 수 있습니다. 릴리스된 태그는 이를 대체하는 릴리스 이후 최소 **14일** 동안 지원되며, 이 기간은 1.0 이후 길어집니다. `X-Nexus-Api-Version`이 `min_api_version`보다 오래된 인식된 태그를 지정한 요청은 현재 사양 링크와 함께 기계 판독용 `426 Upgrade Required`(`api_version_unsupported`)를 받으므로, 도구가 버전 차이를 감지하고 업그레이드할 수 있습니다. 이 헤더는 인증되지 않으므로, 이 게이트는 보안 통제가 아니라 호환성 보조 장치입니다. 값을 위조하면 게이트가 느슨해질 뿐입니다. [API 버전 관리](https://docs.nexus.xyz/exchange/apis-and-rates/api-versioning)도 참조하십시오. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.nexus.xyz/api-reference/ko/guides/errors.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.