오류
모든 오류는 같은 구조와 바뀌지 않는 code를 갖습니다. 분기 처리는 코드를
기준으로 하세요. 메시지는 사람이 읽도록 작성된 것이라 문구가 바뀔 수 있습니다.
{ "error": { "code": "invalid_key", "message": "That API key does not exist." } }
일부 오류에는 이 두 필드 외에 추가 필드가 있습니다. 잘못된 파라미터를 알려 주는
parameter, 기다려야 할 시간을 알려 주는 retry_after, 소진된
할당량에 대한 limit과 used입니다.
전체 오류 코드
| 상태 | 코드 | 발생 조건 |
|---|---|---|
| 400 | missing_query | query가 비어 있거나 없습니다. |
| 400 | unknown_format | format이 여섯 가지 중 하나가 아닙니다. |
| 400 | unknown_column | columns에 존재하지 않는 필드가 있습니다. |
| 400 | format_not_available | 결과 행을 반환하지 않는 곳에 단순 텍스트 형식을 요청했습니다. |
| 400 | per_page_too_large | per_page가 요금제의 행 한도를 넘습니다. 한도는 오류에 포함되어 있습니다. |
| 400 | invalid_json | POST 본문이 올바른 JSON이 아닙니다. |
| 401 | missing_key | Authorization: Bearer 헤더가 없습니다. |
| 401 | invalid_key | 키에 해당하는 계정이 없습니다. |
| 403 | plan_required | 계정에 유료 요금제가 없습니다. |
| 404 | unknown_endpoint | 존재하지 않는 경로입니다. 사용 가능한 경로가 오류에 나열되어 있습니다. |
| 405 | method_not_allowed | 읽기 전용 API입니다. GET을 쓰거나 JSON 본문을 POST로 보내세요. |
| 429 | too_many_requests | 분당 10회보다 빠르게 요청했습니다(API와 MCP 합산). |
| 429 | quota_exceeded | 오늘의 검색 할당량을 모두 사용했습니다. |
| 429 | snippet_quota_exceeded | 오늘의 스니펫 할당량을 모두 사용했습니다. 스니펫 없는 검색은 계속할 수 있습니다. |
오류별 대처 방법
- 400 - 요청이 잘못되었으며, 다시 보내도 해결되지 않습니다. 어떤 파라미터가 문제인지는
parameter필드에 있습니다. - 401, 403 - 키 또는 요금제 문제입니다. 무언가 바뀌기 전에는 재시도해도 소용없습니다.
- 429
too_many_requests-retry_after초만큼 기다렸다가 다시 보내세요. 아무것도 차감되지 않았습니다. - 429
quota_exceeded- 할당량은 다음 UTC 자정에 다시 채워지며, 남은 시간은retry_after에 있습니다. 그 전에 재시도해도 소용없습니다. - 5xx - 저희 쪽 문제입니다. 간격을 점점 늘려 가며 재시도하세요.
오류와 형식
오류는 JSON으로, format=xml을 요청했다면 XML로 반환됩니다. 단순 텍스트
형식에는 오류를 표현할 구조가 없으므로, csv를 요청한 요청이 실패하면 JSON을
받게 됩니다. 따라서 CSV를 읽는 클라이언트는 200처럼 보이는 본문이 모두 결과 행이라고
가정하지 말고 상태 코드를 확인해야 합니다.
이 페이지를 보지 않고 코드 확인하기
GET /은 위의 모든 코드와 그 의미를 JSON으로 나열합니다. 키가 필요 없으므로,
브라우저를 열지 않고도 전체 코드 목록을 기준으로 클라이언트를 만들 수 있습니다.
curl https://api.publicwww.com/다음 코드 예제