Waafir
이 페이지는 사람의 검토를 기다리는 기계 번역입니다. 오류가 있을 수 있습니다.

오류 및 상태 코드

이 페이지는 대출 도메인 API의 모든 경로에서 사용하는 응답 엔벨로프를 정리한 통합 레퍼런스입니다. 경로별 문서에는 해당 경로가 반환하는 상태 코드가 나열되어 있으며, 이 페이지에서는 각 엔벨로프의 형태와 받을 수 있는 명명된 code 값의 카탈로그를 설명합니다.

연동 전에 한 번 읽어 두고, 예상치 못한 2xx 이외의 상태를 받을 때마다 다시 참고하세요.

상태 코드 카탈로그

상태발생 상황예시 경로
200 OK조회 성공, 멱등 재전송, 소프트 취소, 대량 배치 처리 완료, 상태 전환.생성 이외의 모든 경로.
201 Created단일 레코드 경로에서 최초 생성 성공.POST /borrowers.
202 Accepted비동기 가져오기가 시작되었으며, 작업은 백그라운드에서 계속됩니다.POST /imports.
204 No Content현재 어떤 대출 도메인 경로도 반환하지 않습니다.—
400 Bad Request요청 검증 실패: 잘못된 JSON, 잘못된 쿼리, 스키마 위반.모든 변경 경로.
401 UnauthorizedAuthorization 헤더가 없거나, 알 수 없는 토큰이거나, 폐기된 토큰입니다.모든 경로.
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" }
  ]
}
필드타입참고
errorstring사람이 읽을 수 있는 짧은 요약.
fieldErrors[].pathstring문제가 있는 필드까지의 점 표기 경로. (root)는 본문 자체를 가리킵니다(예: JSON 파싱에 실패한 경우).
fieldErrors[].messagestring사람이 읽을 수 있는 설명.

일부 경로는 쿼리 매개변수 실패에 대해 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" }
  ]
}
필드타입참고
errorstring사람이 읽을 수 있는 요약.
codestring안정적인 기계 판독용 코드. 용어집을 참고하세요.
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_CONFLICT409POST /borrowers, POST /loans, POST /payments.같은 id를 가진 유효한 행이 이미 존재합니다.
PORTFOLIO_NOT_FOUND404모든 단일 레코드 쓰기 경로.본문의 portfolioId가 귀하의 조직에 존재하지 않습니다.
REFERENCED_ENTITY_NOT_FOUND422POST /loans, POST /payments.borrowerId 또는 loanId가 같은 포트폴리오에 유효한 상태로 존재하지 않는 행을 참조합니다.
INVALID_STATUS_TRANSITION422PATCH /loans/{loanRef}/status.전환 전후 상태 조합이 전환 매트릭스에 없습니다.
IDEMPOTENCY_CONFLICT409PATCH /loans/{loanRef}/status.이 Idempotency-Key는 이미 다른 상태 전환에 사용되었습니다. 새 전환은 새 키로 보내세요.
IDEMPOTENCY_KEY_REUSED409POST /imports.이 Idempotency-Key는 이미 요청 매개변수(kind, filename, sizeBytes 등)가 다른 가져오기에 사용되었습니다. 응답에는 importId와 mismatchedFields가 포함됩니다. 새 가져오기는 새 키로 보내세요.
MONITORING_INVESTOR_FORBIDDEN403대량 NDJSON을 포함한 모든 모니터링 대출 경로.호출자가 투자자 계정입니다. 투자자는 모니터링 데이터 API를 사용할 수 없습니다.
CHECK_VIOLATION400POST /payments.데이터 규칙을 위반했습니다(보통 채무 면제 불변 조건이며, 스키마 계층이 검증 시점에 같은 형태를 먼저 거부합니다).
NOT_FOUND404GET /borrowers/{id}, GET /payments/{id}, PATCH /loans/.../status, POST /payments/{id}/cancel, GET /loans/{externalId}.조회한 행이 지정한 범위에 유효한 상태로 존재하지 않거나, 다른 조직에 속합니다.
UNKNOWN_KIND400POST /imports.kind가 여섯 가지 대출 종류 중 하나가 아닙니다. 응답에 allowed 배열이 포함됩니다.
COMMIT_FAILED409POST /imports/{id}/commit.플랫폼이 업로드된 파일을 찾을 수 없습니다. 보통 업로드가 끝나지 않은 경우입니다. 업로드를 다시 시도한 후 다시 커밋하세요.

대량 NDJSON 코드 공간

코드상태발생 조건
batch_too_large413본문이 10 000행 또는 10 MB를 초과합니다. 행 수 제한인지 바이트 제한인지는 error와 fieldErrors[].message로 구분합니다.
portfolio_id_required400?portfolioId=<UUID>가 없거나 유효한 UUID가 아닙니다.
portfolio_not_found404?portfolioId=가 귀하의 조직에 유효한 상태로 존재하지 않습니다.
invalid_body400요청 본문을 텍스트로 읽을 수 없습니다.
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 이외 응답으로 올라가는 일은 없습니다. 요청 자체의 형식이 올바르면 배치 전체는 성공한 것이며, 행 단위 코드가 무엇이 반영되었는지 알려 줍니다.

재시도 의미 체계

모든 변경 경로에 적용할 수 있는 안전한 재시도 패턴은 다음과 같습니다.

  1. 논리적 작업마다 결정적인 Idempotency-Key를 생성합니다. UUIDv4에 경로 구분자를 붙이면 충분합니다.
  2. 해당 키를 포함해 요청을 보냅니다.
  3. 2xx, 409 ID_CONFLICT, 409 IDEMPOTENCY_CONFLICT, 409 IDEMPOTENCY_KEY_REUSED, 404, 403, 400, 413, 422 중 하나를 받으면 재시도하지 마세요. 결과가 확정된 것입니다.
  4. 429를 받으면 Retry-After 헤더에 지정된 시간이 지난 후 재시도합니다.
  5. 500 또는 네트워크 오류가 발생하면 지수 백오프를 적용해 적은 고정 횟수까지 재시도합니다. 첫 번째 시도가 도달했는지와 관계없이 Idempotency-Key가 재시도를 안전하게 만들어 줍니다.

성공한 요청을 같은 Idempotency-Key로 재시도하면 원래 요청과 같은 응답이 반환되며, 해당 엔터티에 reused: true가 붙습니다. 이것이 네트워크 장애에서 복구하는 표준 정상 경로입니다.

플랫폼이 절대 반환하지 않는 것

운영 디버깅을 위해 "반환되지 않는 것"을 알아 두면 유용합니다.

  • 플랫폼은 어떤 5xx 상태 코드도 기능으로 취급하지 않습니다. 500은 항상 수정해야 할 버그입니다. 특정 500 형태에 의존하는 클라이언트 로직을 작성하지 마세요.
  • 어떤 404 응답도 테넌트 정보를 노출하지 않습니다. 다른 조직에 존재하는 행에 대한 404는 어디에도 존재하지 않는 행에 대한 404와 똑같아 보입니다. 조직 간 존재 여부를 추론하는 클라이언트 로직을 작성하지 마세요.
  • 어떤 성공 응답도 success: false라는 이름의 본문 필드를 담지 않습니다. 호출 성공 여부의 기준은 상태 코드이며, 본문 형태는 세부 정보를 담습니다.
  • 어떤 쓰기 경로도 경로 매개변수 방식("Location" 헤더)으로 자신의 UUID를 반환하지 않습니다. 생성된 UUID는 응답 본문의 id 필드에 나타납니다.