Errors
Failed requests return JSON with an error message and usually a code field.
Error shape
{
"error": "Invalid or missing API key",
"code": "UNAUTHORIZED"
}Codes
| Code | HTTP | Meaning | What to do |
|---|---|---|---|
| UNAUTHORIZED | 401 | Missing or invalid API key | Check Bearer / X-API-Key and that the key is active |
| QUOTA_EXCEEDED | 429 | Monthly API call quota used up | Upgrade plan or wait until quota resets (Dashboard → Usage) |
| RATE_LIMIT_EXCEEDED | 429 | Per-minute request cap hit | Back off; respect Retry-After header (seconds) |
| USER_NOT_FOUND | 404 | No public user for that @username | Verify the handle; restricted accounts may fail |
| NOT_FOUND | 404 | Tweet or monitor resource not found | Check IDs; monitors must belong to your account |
| UPSTREAM_ERROR | 502 / 504 | Upstream data source error or timeout | Retry with backoff; contact support if persistent |
Rate limits
OnRATE_LIMIT_EXCEEDED, response headers include Retry-After (seconds). Plan caps: Plans & Limits.