API 검증 실패를 빨리 찾아내는 법

API에서 validation 에러가 나면 보통 어디가 문제인지 한 줄짜리 에러 메시지로는 알기 어렵다. 응답 코드만 봐서는 더더욱 그렇다. 이걸 빨리 풀어내려면 요청과 응답을 함께 봐야 한다.

먼저 확인할 것들

요청이 실패했을 때 가장 먼저 볼 건 인증 상태다. 인증이 안 돼 있으면 나머지를 아무리 확인해도 소용없다.

# 요청 상태 확인
curl -i -H "Authorization: Bearer $TOKEN" 'https://api.example.com/users'

# 응답 헤더와 바디를 함께 본다
curl -v -H "Authorization: Bearer $TOKEN" 'https://api.example.com/users' 2>&1 | head -20

인증이 맞다면 다음은 요청 바디의 형식을 본다. JSON인지, form-data인지, query string인지에 따라 파싱이 달라진다.

응답에서 읽을 부분

응답 메시지가 애매하면 로그를 봐야 한다. 같은 요청을 서버 로그에서 찾아보면 validation이 어느 단계에서 실패했는지 나온다.

• 상태 코드 400: 요청 형식이 잘못됨
• 상태 코드 401: 인증 없음
• 상태 코드 403: 권한 없음
• 상태 코드 422: 유효성 검사 실패

상태 코드별로 확인해야 할 항목이 다르다. 422면 바디를 자세히 봐야 하고, 401이면 토큰부터 점검한다.

일단 정상 요청으로 재현해보기

에러가 계속 나면 정상 상태부터 먼저 기록해두는 게 낫다. 같은 엔드포인트에서 정상 요청이 어떻게 보이는지 알면, 실패 요청과의 차이점을 빠르게 찾을 수 있다.

# 정상 요청 저장
curl -v 'https://api.example.com/items' > normal.txt 2>&1

# 실패 요청 저장
curl -v 'https://api.example.com/items?invalid=param' > failed.txt 2>&1

# 비교
diff normal.txt failed.txt

요청 헤더, 파라미터, 바디에서 뭐가 달라졌는지 보이면 원인 찾기가 훨씬 빨라진다.

변수 하나씩 바꿔보기

validation 문제는 대부분 요청의 특정 필드 때문이다. 한 번에 여러 개를 바꾸지 말고, 한 가지씩만 수정해서 어느 부분이 문제인지 확인한다.

예를 들어 이렇게 요청을 보냈다고 하자:

curl -X POST 'https://api.example.com/users' \
  -H 'Content-Type: application/json' \
  -d '{"name": "", "email": "invalid", "age": -5}'

이 요청에서 뭐가 문제인지 알려면:

1. name을 "John"으로 바꿔서 시도
2. email을 올바른 형식으로 바꿔서 시도
3. age를 양수로 바꿔서 시도

각 단계에서 어디서 성공했는지 보면, 어느 필드의 검증이 실패했는지 알 수 있다.

마지막에 남길 것

문제를 풀고 나면 어떤 값이 달라야 했는지 정리해두면 좋다. API 문서를 다시 읽거나 같은 실수를 반복하는 걸 줄일 수 있기 때문이다. 간단한 메모라도 충분하다.