오류 및 상태 코드
이 페이지는 대출 도메인 API의 모든 경로에서 사용하는 응답 엔벨로프를 정리한 통합 레퍼런스입니다. 경로별 문서에는 해당 경로가 반환하는 상태 코드가 나열되어 있으며, 이 페이지에서는 각 엔벨로프의 형태와 받을 수 있는 명명된 code 값의 카탈로그를 설명합니다.
연동 전에 한 번 읽어 두고, 예상치 못한 2xx 이외의 상태를 받을 때마다 다시 참고하세요.
상태 코드 카탈로그
| 상태 | 발생 상황 | 예시 경로 |
|---|---|---|
200 OK | 조회 성공, 멱등 재전송, 소프트 취소, 대량 배치 처리 완료, 상태 전환. | 생성 이외의 모든 경로. |
201 Created | 단일 레코드 경로에서 최초 생성 성공. | POST /borrowers. |
202 Accepted | 비동기 가져오기가 시작되었으며, 작업은 백그라운드에서 계속됩니다. | POST /imports. |
204 No Content | 현재 어떤 대출 도메인 경로도 반환하지 않습니다. | — |
400 Bad Request | 요청 검증 실패: 잘못된 JSON, 잘못된 쿼리, 스키마 위반. | 모든 변경 경로. |
401 Unauthorized | Authorization 헤더가 없거나, 알 수 없는 토큰이거나, 폐기된 토큰입니다. | 모든 경로. |
403 Forbidden | 호출자가 투자자 계정입니다. 투자자는 모니터링 데이터 API를 사용할 수 없습니다(MONITORING_INVESTOR_FORBIDDEN). 관리자가 아닌 사용자의 ?unmask=true는 403이 아니라 PII가 마스킹된 200을 반환합니다. | 모든 경로. |
404 Not Found | 리소스가 존재하지 않거나 다른 조직에 속합니다. | 리소스를 참조하는 모든 경로. |
409 Conflict | 이 id를 가진 유효한 행이 이미 존재하거나, Idempotency-Key가 다른 상태 전환에 재사용되었거나, 커밋 단계에서 업로드된 파일을 찾지 못했습니다. | POST /borrowers, PATCH /loans/.../status, POST /imports/{id}/commit. |
413 Payload Too Large | 대량 NDJSON 배치가 행 수 또는 바이트 제한을 초과했습니다. | POST /bulk/{entity}. |
422 Unprocessable Entity | 참조된 행이 같은 포트폴리오에 유효한 상태로 존재하지 않거나(REFERENCED_ENTITY_NOT_FOUND), 요청된 상태 전환이 전환 매트릭스에 없습니다(INVALID_STATUS_TRANSITION). 검증 실패에는 400이 사용됩니다. | POST /loans, POST /payments, PATCH /loans/{loanRef}/status. |
429 Too Many Requests | 속도 제한을 초과했습니다. 플랫폼은 조직별 속도 제한을 적용하며, 응답 헤더 Retry-After가 초 단위 대기 시간을 알려 줍니다. | 모든 경로. |
500 Internal Server Error | 처리되지 않은 플랫폼 오류입니다. 일시적인 오류로 취급하세요. 같은 Idempotency-Key로 안전하게 재시도할 수 있습니다. | 모든 경로. |
429를 제외한 모든 4xx는 요청 결함으로 취급하세요. 클라이언트 로직은 재시도하지 말고 입력을 거부해야 합니다. 429와 500은 일시적 오류로 취급하여 백오프를 두고 재시도하세요. Idempotency-Key가 있으면 재시도가 안전합니다.
표준 엔벨로프
대출 도메인 API는 성공이 아닌 상태 코드에 세 가지 응답 엔벨로프를 사용합니다. 엔벨로프의 형태를 보면 어떤 종류의 실패인지 알 수 있습니다.
검증 엔벨로프 — 400 Bad Request
스키마 위반, 잘못된 쿼리 매개변수, 잘못된 경로에 사용됩니다.
{
"error": "Validation failed",
"fieldErrors": [
{ "path": "interestRateApr", "message": "interestRateApr must be >= 0" },
{ "path": "termMonths", "message": "termMonths must be > 0" }
]
}| 필드 | 타입 | 참고 |
|---|---|---|
error | string | 사람이 읽을 수 있는 짧은 요약. |
fieldErrors[].path | string | 문제가 있는 필드까지의 점 표기 경로. (root)는 본문 자체를 가리킵니다(예: JSON 파싱에 실패한 경우). |
fieldErrors[].message | string | 사람이 읽을 수 있는 설명. |
일부 경로는 쿼리 매개변수 실패에 대해 fieldErrors[] 대신 errors[]를 반환합니다(프레임워크 관례가 인터페이스마다 다르기 때문입니다). path/message 형태는 동일하므로, 파싱할 때는 두 배열 이름을 서로 바꿔 쓸 수 있는 것으로 취급하세요.
명명된 코드 엔벨로프 — 4xx
플랫폼이 안정적인 code 값으로 이름 붙인 구체적인 원인이 있는 실패에 사용됩니다. fieldErrors는 선택 사항이며, 실패를 특정 필드에 귀속할 수 있는지에 따라 포함 여부가 달라집니다.
{
"error": "a borrower with this id already exists",
"code": "ID_CONFLICT",
"fieldErrors": [
{ "path": "id", "message": "a borrower with this id already exists" }
]
}| 필드 | 타입 | 참고 |
|---|---|---|
error | string | 사람이 읽을 수 있는 요약. |
code | string | 안정적인 기계 판독용 코드. 용어집을 참고하세요. |
fieldErrors[] | array | absent | 실패가 특정 필드를 가리킬 때 존재합니다. |
일부 엔벨로프에는 추가적인 구조화된 컨텍스트가 담깁니다. 예를 들어 batch_too_large에는 초과한 제한을 명시하는 fieldErrors 블록이 포함됩니다. 이러한 내용은 경로별 문서에 나와 있습니다.
단순 오류 엔벨로프 — 404 / 401
추가 컨텍스트가 호출자에게 도움이 되지 않는 간결한 응답에 사용됩니다. 대표적인 예가 404입니다.
{ "error": "Not found" }일부 경로는 { "error": "...", "code": "NOT_FOUND" }를 반환합니다. 404에서 code의 유무는 참고 정보로만 취급하고 이에 의존하지 마세요.
두 가지 코드 공간: 대문자와 소문자
대출 도메인 API는 수집 방식에 따라 의도적으로 분리된 두 개의 서로 다른 code 네임스페이스를 사용합니다.
- 단일 레코드 경로(POST, PATCH, 취소, 대사 GET)는
UPPER_CASE코드 값을 반환합니다:ID_CONFLICT,PORTFOLIO_NOT_FOUND,REFERENCED_ENTITY_NOT_FOUND,INVALID_STATUS_TRANSITION,CHECK_VIOLATION,NOT_FOUND,UNKNOWN_KIND,COMMIT_FAILED,IDEMPOTENCY_CONFLICT,IDEMPOTENCY_KEY_REUSED,MONITORING_INVESTOR_FORBIDDEN. 대량 NDJSON 경로도MONITORING_INVESTOR_FORBIDDEN은 대문자로 반환합니다. - 대량 NDJSON 경로는
lower_case코드 값을 반환합니다:batch_too_large,portfolio_not_found,portfolio_id_required,invalid_body,invalid_json, 그리고 아래에 설명된 행 단위 코드.
클라이언트에서 code로 분기할 때는 대소문자를 정확히 일치시키세요. 두 코드 공간은 각각 독립적으로 안정적이며, 정규화하지 마세요.
오류 코드 용어집
플랫폼은 명명된 모든 실패 유형에 안정적인 code를 붙입니다. 프로그램 분기에는 이 코드를 사용하세요. error 메시지 문구는 바뀔 수 있습니다.
단일 레코드 코드 공간
| 코드 | 상태 | 반환 경로 | 발생 조건 |
|---|---|---|---|
ID_CONFLICT | 409 | POST /borrowers, POST /loans, POST /payments. | 같은 id를 가진 유효한 행이 이미 존재합니다. |
PORTFOLIO_NOT_FOUND | 404 | 모든 단일 레코드 쓰기 경로. | 본문의 portfolioId가 귀하의 조직에 존재하지 않습니다. |
REFERENCED_ENTITY_NOT_FOUND | 422 | POST /loans, POST /payments. | borrowerId 또는 loanId가 같은 포트폴리오에 유효한 상태로 존재하지 않는 행을 참조합니다. |
INVALID_STATUS_TRANSITION | 422 | PATCH /loans/{loanRef}/status. | 전환 전후 상태 조합이 전환 매트릭스에 없습니다. |
IDEMPOTENCY_CONFLICT | 409 | PATCH /loans/{loanRef}/status. | 이 Idempotency-Key는 이미 다른 상태 전환에 사용되었습니다. 새 전환은 새 키로 보내세요. |
IDEMPOTENCY_KEY_REUSED | 409 | POST /imports. | 이 Idempotency-Key는 이미 요청 매개변수(kind, filename, sizeBytes 등)가 다른 가져오기에 사용되었습니다. 응답에는 importId와 mismatchedFields가 포함됩니다. 새 가져오기는 새 키로 보내세요. |
MONITORING_INVESTOR_FORBIDDEN | 403 | 대량 NDJSON을 포함한 모든 모니터링 대출 경로. | 호출자가 투자자 계정입니다. 투자자는 모니터링 데이터 API를 사용할 수 없습니다. |
CHECK_VIOLATION | 400 | POST /payments. | 데이터 규칙을 위반했습니다(보통 채무 면제 불변 조건이며, 스키마 계층이 검증 시점에 같은 형태를 먼저 거부합니다). |
NOT_FOUND | 404 | GET /borrowers/{id}, GET /payments/{id}, PATCH /loans/.../status, POST /payments/{id}/cancel, GET /loans/{externalId}. | 조회한 행이 지정한 범위에 유효한 상태로 존재하지 않거나, 다른 조직에 속합니다. |
UNKNOWN_KIND | 400 | POST /imports. | kind가 여섯 가지 대출 종류 중 하나가 아닙니다. 응답에 allowed 배열이 포함됩니다. |
COMMIT_FAILED | 409 | POST /imports/{id}/commit. | 플랫폼이 업로드된 파일을 찾을 수 없습니다. 보통 업로드가 끝나지 않은 경우입니다. 업로드를 다시 시도한 후 다시 커밋하세요. |
대량 NDJSON 코드 공간
| 코드 | 상태 | 발생 조건 |
|---|---|---|
batch_too_large | 413 | 본문이 10 000행 또는 10 MB를 초과합니다. 행 수 제한인지 바이트 제한인지는 error와 fieldErrors[].message로 구분합니다. |
portfolio_id_required | 400 | ?portfolioId=<UUID>가 없거나 유효한 UUID가 아닙니다. |
portfolio_not_found | 404 | ?portfolioId=가 귀하의 조직에 유효한 상태로 존재하지 않습니다. |
invalid_body | 400 | 요청 본문을 텍스트로 읽을 수 없습니다. |
invalid_json | (행 단위) | 행이 유효한 JSON이 아닙니다. 행 단위 errors[] 배열 안에 나타나며, 배치는 200을 반환합니다. |
이 용어집에 없는 코드는 이 페이지의 마지막 개정 이후 플랫폼이 새로운 명명된 코드를 추가했음을 뜻합니다. 엔지니어링 팀이 연관 지어 분석할 수 있도록 code 값을 애플리케이션 오류와 함께 항상 그대로 기록하세요.
행 단위 오류 코드(대량 및 비동기 가져오기)
대량 NDJSON과 비동기 가져오기는 모두 행 단위 오류를 반환합니다. 대량 인터페이스는 한 가지 값 집합을 사용하고, 비동기 가져오기 인터페이스는 비슷하지만 약간 다른 집합을 사용합니다(특히 validation_failed 대신 validation_error를 포함하는데, 이는 더 오래된 인터페이스임을 반영합니다). 행 단위 항목은 엔벨로프 수준의 실패가 아니라 성공한 배치 안의 개별 행 실패를 나타냅니다.
대량 NDJSON 행 단위 코드
| 행 단위 코드 | 발생 조건 |
|---|---|
validation_failed | 행이 스키마 검증에 실패했습니다. message 필드에 검증 오류가 담깁니다. |
fk_violation | 행의 외래 키 참조(예: borrowerId, loanId)가 같은 포트폴리오의 유효한 행으로 확인되지 않습니다. |
unique_violation | 같은 (portfolio, externalId) 또는 id를 가진 유효한 행이 이미 존재합니다. (별도의 id_conflict 행 단위 코드는 없으며, 두 종류의 호출자 ID 충돌 모두 여기에 나타납니다.) |
check_violation | 데이터 규칙을 위반했습니다. 보통 상환에 대한 채무 면제 규칙입니다. |
db_error | 이 행을 저장하는 중 예기치 않은 오류가 발생했습니다. 행은 실패로 보고되고 배치는 계속됩니다. |
invalid_json | 행이 유효한 JSON이 아닙니다. 플랫폼은 배치의 나머지를 처리합니다. |
비동기 가져오기 행 단위 코드
| 행 단위 코드 | 발생 조건 |
|---|---|
parse_error | 줄이 유효한 JSON이 아닙니다. |
validation_error | 행이 스키마 검증에 실패했습니다. |
portfolio_mismatch | 행의 portfolioId가 가져오기의 기준 포트폴리오와 일치하지 않습니다. |
processor_error | 이 행을 처리하는 중 처리기가 예기치 않게 실패했습니다. |
행 저장 중 발생한 오류(참조 대상 누락, 중복, 데이터 규칙 위반)는 위 코드 중 하나로 나타나며, 세부 내용은 errorMessage에 담깁니다.
행 단위 오류가 대량 인터페이스의 최상위 200 이외 응답으로 올라가는 일은 없습니다. 요청 자체의 형식이 올바르면 배치 전체는 성공한 것이며, 행 단위 코드가 무엇이 반영되었는지 알려 줍니다.
재시도 의미 체계
모든 변경 경로에 적용할 수 있는 안전한 재시도 패턴은 다음과 같습니다.
- 논리적 작업마다 결정적인
Idempotency-Key를 생성합니다. UUIDv4에 경로 구분자를 붙이면 충분합니다. - 해당 키를 포함해 요청을 보냅니다.
2xx,409 ID_CONFLICT,409 IDEMPOTENCY_CONFLICT,409 IDEMPOTENCY_KEY_REUSED,404,403,400,413,422중 하나를 받으면 재시도하지 마세요. 결과가 확정된 것입니다.429를 받으면Retry-After헤더에 지정된 시간이 지난 후 재시도합니다.500또는 네트워크 오류가 발생하면 지수 백오프를 적용해 적은 고정 횟수까지 재시도합니다. 첫 번째 시도가 도달했는지와 관계없이Idempotency-Key가 재시도를 안전하게 만들어 줍니다.
성공한 요청을 같은 Idempotency-Key로 재시도하면 원래 요청과 같은 응답이 반환되며, 해당 엔터티에 reused: true가 붙습니다. 이것이 네트워크 장애에서 복구하는 표준 정상 경로입니다.
플랫폼이 절대 반환하지 않는 것
운영 디버깅을 위해 "반환되지 않는 것"을 알아 두면 유용합니다.
- 플랫폼은 어떤
5xx상태 코드도 기능으로 취급하지 않습니다.500은 항상 수정해야 할 버그입니다. 특정500형태에 의존하는 클라이언트 로직을 작성하지 마세요. - 어떤
404응답도 테넌트 정보를 노출하지 않습니다. 다른 조직에 존재하는 행에 대한404는 어디에도 존재하지 않는 행에 대한404와 똑같아 보입니다. 조직 간 존재 여부를 추론하는 클라이언트 로직을 작성하지 마세요. - 어떤 성공 응답도
success: false라는 이름의 본문 필드를 담지 않습니다. 호출 성공 여부의 기준은 상태 코드이며, 본문 형태는 세부 정보를 담습니다. - 어떤 쓰기 경로도 경로 매개변수 방식("Location" 헤더)으로 자신의 UUID를 반환하지 않습니다. 생성된 UUID는 응답 본문의
id필드에 나타납니다.