Using the API

Errors

Problem details, stable error codes, and what to do about each.

Errors are RFC 9457 problem details with Content-Type: application/problem+json. Branch on code, which is stable. detail is written for people and can change.

response

{
  "type": "https://crawlfeed.dev/errors/insufficient_credits",
  "title": "Insufficient credits",
  "status": 402,
  "detail": "This call costs 1 credit and the balance is 0.",
  "code": "insufficient_credits",
  "request_id": "req_01K5…"
}

Codes

Code	Status	Meaning	What to do
unauthorized	401	The key is missing, malformed or revoked.	Check the Authorization header. Create a new key in the dashboard if needed.
insufficient_credits	402	The balance is lower than the price of the call.	Buy a credit pack. Nothing was charged.
not_found	404	The account, post or route does not exist, or the platform does not serve that operation.	Check the id or handle, and the platform page for what it serves.
invalid_request	400	A parameter is missing or malformed.	Read `detail`: it names the parameter.
rate_limited	429	This key sent requests faster than its limit.	Wait `retry_after` seconds, then retry.
platform_unavailable	503	The platform is failing or blocking right now.	Retry with backoff. Refunded.
upstream_timeout	504	The platform did not answer in time.	Retry. Refunded.
internal_error	500	Something broke on our side.	Retry, and send us the `request_id` if it persists. Refunded.

Operations a platform does not serve

Platforms differ, and the API says so rather than returning an empty list that looks like “no data”. Asking a platform for an operation it does not have (say, /v1/instagram/audience) returns 404 not_found with a detail naming the route, and is not charged. The coverage matrix shows who serves what.

Retrying

Retry rate_limited, platform_unavailable and upstream_timeout with exponential backoff. Do not retry the others unchanged. Every error carries a request_id; include it when you contact us.