TwitterScore.io / API docs

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.