Errors
An error body looks like this:
{"success": false, "message": "API key has to be provided",
"error": {"code": "api_key_missing", "message": "API key has to be provided",
"docs_url": "https://twitterscore.io/developers/errors/"}}
success: false is present on every error. The error object is present on authentication, account-lookup, rate-limit and unexpected errors; parameter checks made by individual endpoints (for example an unknown by, days, date or category_id value) still answer with success: false and message only, and with HTTP 200. One endpoint (get_categorized_followers_count) can answer an internal failure with a legacy body where error is a plain string and message is absent. So branch on success first, treat message and error as optional, and check that error is an object before reading error.code.
HTTP statuses
Clients built on the first version of the API branch on the body, not on the status code. For that reason errors are currently returned with HTTP 200 and success: false; the two rate limits (rate_limited, quota_exceeded) are the exception and already answer with HTTP 429. The real HTTP statuses for the other codes are enabled after a 30-day notice in the Changelog. Code that checks success first works before and after the switch.
Codes
error.code |
Meaning | HTTP status today | HTTP status after the switch |
|---|---|---|---|
api_key_missing |
No API key in the request. | 200 | 401 |
api_key_invalid |
The key is unknown. | 200 | 401 |
api_access_deactivated |
API access of the account is off (expired or cancelled plan): renew on the dashboard. | 200 | 403 |
api_key_revoked |
This key was revoked; the account is still active, create a new key. | 200 | 403 |
invalid_params |
A required parameter is missing or malformed. | 200 | 400 |
account_not_found |
No tracked account matches the username / twitter_id. | 200 | 404 |
method_not_allowed |
Only GET is supported. Sent for HEAD/OPTIONS; POST and other unsafe methods are stopped earlier with an HTML 403. | 200 | 405 |
rate_limited |
Per-minute rate exceeded; retry after Retry-After seconds. |
429 | 429 |
quota_exceeded |
Monthly quota exhausted; upgrade or wait for the window to reset. | 429 | 429 |
server_error |
Unexpected server error; retry later. | 200 | 500 |
rate_limited responses carry Retry-After: 60 (the length of the per-minute window; waiting that long is always enough); quota_exceeded has no Retry-After (the 30-day window resets on its own, see Rate limits).
This page as Markdown.