> ## Documentation Index
> Fetch the complete documentation index at: https://developers.argosidentity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 오류 코드와 재시도

> Unit API 오류 응답 형식, 오류 코드별 의미와 대응, 응답 헤더, 재시도 기준과 버전 정책을 안내합니다.

Unit API는 결과를 만들지 못한 호출에 `200`이 아닌 HTTP 상태와 오류 본문을 돌려줍니다. **오류 응답은 과금되지 않습니다.** 호출 기록은 남고, 체험(Trial) 프로젝트에서는 월 호출 수에 포함됩니다.

## 오류 응답 형식

```json theme={null}
{
  "code": "MISSING_PARAMETER",
  "message": "idImage: Invalid input: expected string, received undefined"
}
```

| 필드 | 설명 |
| - | - |
| `code` | 오류 종류를 가르는 영문 코드. **분기는 이 값으로 하세요.** |
| `message` | 사람이 읽는 설명. 어느 필드가 문제인지 알려 줄 때가 많지만, 예고 없이 바뀌므로 분기 조건으로 쓰지 마세요. |

***

## 응답 헤더

| 헤더 | 언제 오는지 | 설명 |
| - | - | - |
| `X-Request-Id` | 모든 응답 | HTTP 요청 하나의 ID |
| `X-Trace-Id` | 모든 응답 | 그 요청이 만든 내부 처리 흐름 전체의 ID |
| `X-Tx-Id` | 본문을 읽고 처리 단계에 들어간 호출 | 성공 응답의 `txId`와 같은 값. 오류 응답에도 오므로 본문을 읽지 못해도 TX ID를 남길 수 있습니다 |
| `Retry-After` | `429`, 일부 `503` | 다시 호출하기까지 기다릴 초(정수) |

`X-Tx-Id`는 본문을 읽기 전에 거절된 요청(깨진 JSON `400 REQUEST_INVALID`, 본문 크기 초과 `413 REQUEST_TOO_LARGE`)에는 없습니다. 문의할 때는 `X-Tx-Id`와 함께 `X-Request-Id`·`X-Trace-Id`도 알려 주세요.

***

## 오류 코드

### 요청 문제 (4xx)

요청을 고치기 전에는 같은 결과가 나옵니다. **그대로 재시도하지 마세요.**

| HTTP | code | 의미 | 대응 |
| :-: | - | - | - |
| 400 | `MISSING_PARAMETER` | 필수 필드를 보내지 않았습니다 | 빠진 필드를 넣어 다시 호출합니다 |
| 400 | `INVALID_PARAMETER_FORMAT` | 필드의 타입이나 형식이 다릅니다. 빈 문자열과 `null`도 여기 해당합니다 | 값을 고쳐 다시 호출합니다 |
| 400 | `UNKNOWN_PARAMETER` | 계약에 없는 필드나 쿼리 파라미터를 보냈습니다 | 필드 이름의 오타를 확인합니다 |
| 400 | `PARAMETER_OUT_OF_RANGE` | 값이 허용 범위 밖입니다. 이미지 크기 초과가 여기 해당합니다 | 값을 범위 안으로 고칩니다 |
| 400 | `REQUEST_INVALID` | 요청을 해석할 수 없습니다. 깨진 JSON, 이미지로 디코딩되지 않는 Base64가 여기 해당합니다 | 요청 본문과 이미지 인코딩을 확인합니다 |
| 401 | `AUTHENTICATION_FAILED` | `x-api-key` 헤더가 없거나 해석할 수 없습니다 | 헤더 이름과 값을 확인합니다 |
| 401 | `INVALID_API_KEY` | 없는 키이거나 재발급으로 폐기된 키입니다. 다른 리전 호스트로 호출해도 이 오류가 납니다 | 대시보드에서 현재 키와 프로젝트 리전을 확인합니다 |
| 403 | `ACCESS_FORBIDDEN` | 키는 맞지만 프로젝트 상태상 쓸 수 없습니다(종료 프로젝트) | 프로젝트 상태를 확인합니다 |
| 409 | `STATE_CONFLICT` | 같은 요청이 기관에서 아직 처리 중입니다. 신분증 진위확인과 체류 확인에서만 납니다 | 잠시 후 다시 호출합니다 |
| 413 | `REQUEST_TOO_LARGE` | 요청 본문이 상한을 넘었습니다 | 이미지 크기를 줄입니다 |
| 415 | `UNSUPPORTED_MEDIA_TYPE` | `Content-Type`이 `application/json`이 아닙니다 | 헤더를 고칩니다 |
| 422 | `ADDITIONAL_AUTH_UNSUPPORTED` | 기관이 본인 추가인증을 요구했습니다. Unit API는 추가인증을 지원하지 않습니다 | 재시도해도 같습니다. 다른 수단으로 확인합니다 |
| 429 | `TRIAL_LIMIT_EXCEEDED` | 체험 프로젝트의 월 호출 한도를 다 썼습니다 | `Retry-After` 이후(다음 달 1일 00:00 UTC)에 호출하거나, 프로젝트를 전환합니다 |
| 429 | `RATE_LIMIT_EXCEEDED` | 호출 빈도 상한을 넘었습니다 | `Retry-After` 이후에 호출합니다 |

### 입력 이미지 문제 (502)

엔진은 정상으로 답했지만 보낸 이미지에서 읽을 것을 찾지 못한 경우입니다. 같은 이미지를 다시 보내도 결과가 같으므로, **다시 촬영한 이미지로 호출하세요.**

| HTTP | code | 의미 | 대응 |
| :-: | - | - | - |
| 502 | `ID_NOT_RECOGNIZED` | ID-OCR이 신분증 앞면에서 글자를 찾지 못했습니다 | 잘림·흐림·빛 반사를 줄여 다시 촬영합니다. 발급 국가와 신분증 종류가 맞는지도 확인합니다 |
| 502 | `FACE_NOT_DETECTED` | FACE-COM·FACE-LIVE-PSV가 이미지에서 얼굴을 찾지 못했습니다 | `message`에 어느 이미지인지(`originFace`·`targetFace`·`faceImage`) 나옵니다. 그 이미지를 다시 촬영합니다 |

### 서버·기관 문제 (5xx)

보내신 요청의 문제가 아닙니다. 아래 기준으로 재시도하세요.

| HTTP | code | 의미 | 대응 |
| :-: | - | - | - |
| 500 | `INTERNAL_SERVER_ERROR` | 서버 내부 오류입니다 | 간격을 두고 몇 번만 재시도합니다. 계속되면 문의합니다 |
| 502 | `UPSTREAM_ERROR` | 검증 엔진이나 외부 기관이 요청을 처리하지 못했습니다 | 간격을 두고 재시도합니다. 같은 입력에서 반복되면 문의합니다 |
| 502 | `AGENCY_REQUEST_REJECTED` | ARGOS가 기관에 보낸 요청을 기관이 거절했습니다. 보내신 요청을 고칠 필요는 없습니다 | 재시도하지 말고 TX ID와 함께 문의합니다 |
| 503 | `UPSTREAM_UNAVAILABLE` | 기관·엔진이 일시적으로 응답할 수 없습니다. 기관 점검 시간에 자주 납니다 | `Retry-After`가 있으면 그 뒤에, 없으면 간격을 늘려 가며 재시도합니다 |
| 504 | `UPSTREAM_TIMEOUT` | 엔진·기관 응답이 제한 시간을 넘었습니다. **처리됐는지 알 수 없는 상태입니다** | 바로 재시도하지 말고 아래 [중복 호출과 재시도](#중복-호출과-재시도)를 따릅니다 |

> [!NOTE]
>
> 같은 `v1` 안에서도 오류 코드는 늘어날 수 있습니다. 모르는 `code`를 받으면 HTTP 상태(4xx·5xx)를 기준으로 처리하세요.

***

## 중복 호출과 재시도

Unit API는 멱등 키를 받지 않습니다. **같은 요청을 두 번 보내면 두 건으로 처리하고 두 번 과금합니다.**

* 응답을 받지 못했거나 `504 UPSTREAM_TIMEOUT`을 받은 호출도 처리됐을 수 있습니다. 그대로 재시도하기 전에 대시보드 호출 내역에서 그 호출이 있는지 확인하세요.
  * `X-Tx-Id` 헤더를 받았다면 TX ID로 검색합니다.
  * 받지 못했다면 호출 내역 CSV의 `referenceId` 열에서 찾습니다. 그러려면 **호출마다 다른 `referenceId`를 보내야 합니다.**
* 5xx 재시도는 간격을 늘려 가며 3회 정도로 제한하세요. 예: 1초, 2초, 4초 후
* 체험 프로젝트는 오류 호출도 월 한도에 포함되므로 재시도 횟수를 더 엄격히 제한하세요.

### 응답 시간

기관 조회는 기관 응답을 기다리므로 수 초가 걸릴 수 있습니다. 예를 들어 운전면허증 진위확인은 5\~12초 걸리는 경우가 있습니다. 클라이언트 타임아웃은 넉넉히(60초 이상) 두세요. 타임아웃을 짧게 잡으면 처리된 호출을 실패로 보고 재시도해 두 번 과금될 수 있습니다.

***

## 버전 정책

경로의 `v1`이 계약의 버전입니다.

**같은 버전에서 적용되는 변경**: 모르는 값을 만나도 실패하지 않게 구현하세요.

* API 추가, 선택 요청 필드 추가, 응답 필드 추가
* 필수 요청 필드가 선택으로 바뀌는 것
* enum 값 추가, 오류 `code` 추가, `message` 문구 개선

**새 버전으로 제공하는 변경**: `v1`을 덮어쓰지 않습니다.

* API 제거, 경로·메서드 변경
* 필수 요청 필드 추가, 선택 필드가 필수로 바뀌는 것
* 응답 필드 삭제·이름 변경, enum 값이나 오류 `code`의 삭제·이름·의미 변경
* 필드 타입·`null` 허용 규칙·성공 조건·HTTP 상태 변경

`agency`, `data.raw`처럼 "계약으로 보장하지 않는다"고 적힌 필드는 이 정책의 대상이 아닙니다. 기관·엔진이 바꾸면 예고 없이 달라집니다.

***

## 문의할 때

아래 값을 함께 보내 주세요.

* TX ID (`txId` 또는 `X-Tx-Id`)
* `X-Request-Id`, `X-Trace-Id`
* 호출 시각(UTC)과 호출한 API
* 받은 HTTP 상태와 `code`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.