Official docs group errors as JSON with error and message. Use message as the operator-facing text. The three codes this page exists for are 401, 429, and the fact that a successful envelope still uses a string body. The POST is https://api.trendsapi.ai/api. Envelope shape is on the response envelope.
401
No Bearer header, a truncated key, or a key from the wrong product. Official fix: Authorization: Bearer <api_key>. How to send it is on authentication.
A 401 is not "Google Trends is down." It is not a pytrends cookie miss. Do not add hl or a proxy.
429
Official table: status 429, code rate_limited, cause monthly quota used. The fix named in docs is to upgrade or wait for reset. Current plan text lives on pricing. This page does not quote a number.
Official usage notes also say failed 4xx and 5xx calls do not count as a successful lookup. Retry with jitter after a 429. Do not tight-loop get_time_series to "use up" a window list. Collapse windows into one get_growth call.
400 and the string body
| Status | Code | Fix |
|---|---|---|
| 400 | missing_parameter |
Add the field named in message |
| 400 | invalid_source |
Copy a source from the sources reference |
| 404 | not_found |
Check keyword and source |
| varies | data_unavailable |
Retry or change the query |
| 500 | internal_error |
Retry, then email [email protected] |
Parse body even on some error payloads. On 200, always parse body. An inner date_out_of_range row is not this table. It is a window the source cannot cover. How to parse is on parse the body.