API 오류를 해결하는 기본 원리
API 호출 오류는 보통 요청 주소(URL), 요청 방식(GET·POST 등), 데이터 형식, 인증 정보, 서버 상태 중 하나에서 발생합니다. 초보자는 오류 메시지만 보고 코드를 바로 바꾸기보다 요청과 응답을 먼저 확인하는 학습방법이 좋습니다. Python의 requests 라이브러리에서는 response.status_code, response.text, response.headers를 출력하면 문제를 좁힐 수 있습니다. 특히 응답 본문에는 서버가 알려 주는 구체적인 원인이 담겨 있는 경우가 많습니다.
오류를 확인하는 기초 점검 코드
호출 결과를 안전하게 확인하려면 상태 코드와 본문을 함께 출력하세요. 예를 들어 response = requests.get(url, timeout=10) 후 print(response.status_code), print(response.text)를 실행합니다. JSON 응답이라고 확신할 수 없으므로 처음부터 response.json()만 호출하면 JSON 해석 오류가 추가로 발생할 수 있습니다. 상태 코드가 200 범위인지 확인한 뒤 JSON으로 변환하는 습관이 중요합니다.
문제 해결 순서
첫째, API 문서에서 엔드포인트와 HTTP 메서드를 다시 확인합니다. 둘째, 쿼리 파라미터와 요청 본문의 필수 항목, 자료형을 확인합니다. 셋째, API 키를 헤더 또는 파라미터의 올바른 위치에 넣었는지 봅니다. 넷째, 네트워크 연결과 서버의 일시적 장애 가능성을 확인합니다. 마지막으로 민감한 API 키를 출력하거나 코드 저장소에 올리지 않았는지도 점검해야 합니다.
예외 처리의 필요성
실제 프로그램에서는 연결 실패나 응답 지연이 언제든 발생할 수 있습니다. requests.exceptions.RequestException을 처리하고 timeout 값을 지정하면 프로그램이 무한히 기다리거나 갑자기 종료되는 상황을 줄일 수 있습니다. 다만 오류를 무조건 무시하지 말고, 상태 코드와 오류 내용을 로그로 남겨 원인을 다시 확인할 수 있게 해야 합니다.
자주 묻는 질문
400 Bad Request는 왜 발생하나요?
400은 서버가 요청 내용을 이해할 수 없을 때 주로 반환합니다. 필수 파라미터 누락, 잘못된 날짜 형식, 문자열이어야 할 값에 숫자를 넣은 경우 등이 원인입니다. API 문서의 요청 예시와 내 params 또는 json 데이터를 한 항목씩 비교하세요. POST 요청에서 JSON을 보낼 때는 data= 대신 json=을 사용해야 하는 API도 많습니다.
401 Unauthorized와 403 Forbidden의 차이는 무엇인가요?
401은 인증 정보가 없거나 유효하지 않다는 뜻입니다. API 키 오타, 만료된 토큰, Authorization 헤더 형식 오류를 확인하세요. 403은 인증은 되었지만 해당 기능을 사용할 권한이 없을 때 흔히 발생합니다. 요금제, 접근 권한, 허용된 IP 또는 서비스 설정을 확인해야 합니다.
404 Not Found가 나오면 URL만 확인하면 되나요?
URL 확인이 우선이지만 그것만으로 충분하지 않습니다. API 버전(v1, v2), 경로의 대소문자, 끝의 슬래시, 경로 변수 값, 그리고 GET 대신 POST를 써야 하는지까지 확인하세요. 브라우저에서 주소가 열린다고 해서 API 엔드포인트가 올바른 것은 아닙니다.
response.json()에서 오류가 발생하는 이유는 무엇인가요?
응답이 항상 JSON이라는 보장은 없습니다. 오류 상황에서 서버가 HTML 오류 페이지나 빈 문자열을 반환할 수 있습니다. 먼저 response.status_code와 response.text를 확인하세요. Content-Type 헤더가 application/json인지 확인하는 것도 도움이 됩니다. 정상 응답일 때만 response.json()을 호출하는 방식이 안전합니다.
API 호출이 오래 걸리거나 멈춘 것처럼 보입니다.
timeout을 지정하지 않으면 네트워크 상황에 따라 오래 대기할 수 있습니다. requests.get(url, timeout=10)처럼 제한 시간을 설정하세요. Timeout 오류가 반복된다면 인터넷 연결, 서버 상태, URL 도메인, 회사·학교 네트워크의 방화벽 제한을 확인합니다. 같은 요청을 짧은 간격으로 반복해 서버가 느려진 경우도 있습니다.
429 Too Many Requests는 어떻게 해결하나요?
429는 정해진 호출 횟수 제한을 넘었다는 의미입니다. 반복문에서 너무 빠르게 요청하지 않는지 확인하고, time.sleep()으로 간격을 둡니다. 응답 헤더의 Retry-After 값이 있다면 그 시간만큼 기다리는 것이 좋습니다. 같은 데이터를 여러 번 요청해야 한다면 결과를 저장하는 캐시를 적용하면 호출 수를 줄일 수 있습니다.