Error codes — Docs

Every error on APIHiver is JSON with the same shape:

{ "error": { "code": "QUOTA_EXCEEDED", "message": "Monthly quota exceeded." } }

Use code in your program logic. message is for humans and may change.

Errors from the gateway

These are returned by APIHiver itself, before or instead of reaching the provider's server.

HTTP	Code	What happened	What to do
401	`UNAUTHORIZED`	The `X-API-Key` header is missing.	Send your key in the `X-API-Key` header.
401	`INVALID_API_KEY`	The key doesn't exist, was deleted or has expired.	Check for typos, or create a new key in Console → API Keys.
403	`FORBIDDEN`	The key is valid, but you have no active subscription to this API (never subscribed, cancelled, expired, past due, or blocked by the provider).	Subscribe on the API's Pricing tab, or pay any open invoice in Console → Billing.
404	`NOT_FOUND`	No published API exists at this address.	Check the API name in the URL (`https://<api-name>.p.apihiver.com`).
404	`ENDPOINT_NOT_FOUND`	The API exists, but has no endpoint with this method and path.	Check the method (`GET` vs `POST`) and the path on the endpoint's page.
413	`REQUEST_TOO_LARGE`	The request body is bigger than this API allows.	Send a smaller file, or use a URL instead of uploading, if the API supports it.
429	`RATE_LIMITED`	Too many requests per second for your plan.	Slow down and retry after `X-RateLimit-Requests-Reset` seconds.
429	`QUOTA_EXCEEDED`	Your plan's monthly quota is used up.	Wait for the next billing month, or switch to a bigger plan.
429	`TOO_MANY_CONCURRENT_REQUESTS`	Too many requests in flight at once for your plan.	Wait for earlier requests to finish.
502	`BAD_GATEWAY`	The provider's server didn't answer in time or couldn't be reached. This call doesn't count towards your quota.	Retry after a few seconds. If it persists, tell the provider (quote the `X-Request-Id`).

Errors from the API itself

Everything else (for example 400 for a missing parameter or 404 for a record that doesn't exist) comes from the provider's API. Each endpoint's page lists the errors it returns, with real examples, on its Example Responses tab.

Getting help with an error

Every response, including errors, has an X-Request-Id header. Include it when you ask for help in the API's Discussions, via Contact Provider, or with APIHiver support: it lets us find the exact call.