Error Handling & HTTP Status Codes — ApiTwitter

ApiTwitter error reference: JSON error format, HTTP codes (400, 401, 402, 404, 422, 429, 500). Troubleshoot missing API key, insufficient credits, rate limits, and bad requests on the Twitter/X API.

Error Response Format

All errors return a JSON object with status and msg fields:

{
  "status": "error",
  "msg": "Description of what went wrong"
}

HTTP Status Codes

Code	Meaning	Common Cause
400	Bad Request	Missing proxy, invalid cookies, missing required parameter
401	Unauthorized	Missing or invalid X-API-Key header
402	Payment Required	Insufficient credit balance
404	Not Found	User, tweet, or resource doesn’t exist
422	Unprocessable Entity	Invalid request body or parameter format
429	Too Many Requests	QPS rate limit exceeded
500	Internal Server Error	Unexpected server error

Common Errors & Solutions

Missing API Key (401)

{"status": "error", "msg": "X-API-Key header is required"}

Fix: Add the X-API-Key header to your request.

Missing Proxy (400)

{"status": "error", "msg": "proxy is required. We do not provide proxies — you must supply your own proxy URL with every request."}

Fix: Include a "proxy" field in the JSON request body.

Insufficient Credits (402)

{"status": "error", "msg": "Insufficient credits. Please top up your balance.", "required_credits": 225}

Fix: Top up your credit balance at apitwitter.com/billing.

Rate Limited (429)

{"status": "error", "msg": "Rate limit exceeded.", "tier": "Free", "qps_limit": 0.2, "retry_after": 1.5}

Fix: Wait for retry_after seconds, or top up balance to increase your QPS tier.

Always check the status field in response JSON. Successful responses return "status": "success".