파일 업로드 API가 응답 형식을 일관되게 주지 않을 때

문제를 전체로 보지 말고 단계별로 본다

파일 업로드 API가 항상 같은 형식으로 응답하지 않는다면, 문제의 범위를 너무 크게 잡지 말아야 한다. "모든 파일 처리 로직"을 다시 쓰려고 하면 오히려 더 복잡해진다. 먼저 어떤 조건에서 응답이 달라지는지 파악해야 한다.

API 요청-응답 문제의 핵심은 화면만 보고 판단하지 않는 것이다. 요청 파라미터가 올바른지, 서버에서 받은 파일이 제대로 처리되는지, 응답 바디가 예상대로 구성되는지를 단계별로 확인해야 한다.

요청 파라미터부터 확인한다

응답이 일관되지 않은 이유는 대부분 요청이 다르기 때문이다:

• 먼저 볼 값: 업로드하는 파일의 크기, 형식, 인코딩
• 함께 비교할 값: 정상일 때의 요청과 응답을 비교
• 남겨둘 기록: 요청 헤더, 응답 코드, 서버 로그

응답 바디를 직접 확인한다

API 쪽 문제는 브라우저의 개발자 도구만으로는 놓치는 값이 많다. curl이나 httpie 같은 도구로 직접 요청을 보내고 응답을 확인해야 한다:

curl -i -F "[email protected]" 'https://example.com/api/upload'

이 명령으로 실제 HTTP 헤더와 응답 바디를 전부 확인할 수 있다.

인증 상태를 의심한다

응답이 일관되지 않는 흔한 원인은 인증 상태의 변화다. 로그인이 만료되었거나, 권한이 불충분하거나, 토큰이 갱신되는 시점에 따라 응답이 달라질 수 있다. 파일을 업로드할 때마다 인증 상태를 로그에 남겨두면 패턴을 찾기가 쉬워진다.

단계별로 검증한다

같은 문제가 반복되는 것을 방지하려면 확인 순서를 고정한다:

1. 원래 증상이 같은 조건에서 다시 나타나는지 확인한다
2. 요청 파라미터, 응답 코드, 서버 로그에서 바뀐 부분을 명확히 설명할 수 있는지 확인한다
3. 실제 브라우저 화면, API 응답, 서버 로그 중 적어도 하나를 최종 확인한다

다음을 위해 기록한다

파일 업로드 문제를 해결한 후, 어떤 요청 조건이 어떤 응답 형식을 만들었는지 정리해두면, 비슷한 문제를 훨씬 빠르게 처리할 수 있다.