Error reference

Every error response carries a machine-readable error code, a human message, a request_id, and a docs_url linking to the matching entry below.

{
  "error": "insufficient_credits",
  "message": "insufficient credits: have 0, need 1",
  "request_id": "37f01edb-0163-42a1-ac51-0acaef979800",
  "docs_url": "https://apilib.io/docs/errors#insufficient_credits"
}

HTTP 401

unauthorized

Missing or invalid credentials

The request carried no usable credential. On the developer API that means the x-api-key header was absent or did not match an active key — revoked and expired keys report the same code. On the website it means you are not signed in, or your session has expired or been signed out elsewhere. The two cases share one code because API Gateway returns a single unauthorized response for the whole API.

Fix: Developers: send the key as an x-api-key header, and allow up to a minute after creating one. On the website: sign in again.

HTTP 402

insufficient_credits

Not enough credits

Your balance is lower than the cost of the tool you ran. The call is rejected before the tool runs, so nothing is charged. This is the same code whether you were on the website or the developer API — both spend from one balance.

Fix: Top up your balance, or choose a cheaper tool: the response tells you both the cost and what you hold. A new account starts with 20 credits.

HTTP 402

endpoint_not_found

Unknown endpoint

The path resolved to a slug with no configuration, so no cost could be determined.

Fix: Check the path against the catalogue. Planned endpoints are listed but not callable.

HTTP 402

invalid_route

Malformed route

The request path did not match the expected /v1/<endpoint> shape.

Fix: Call the versioned path exactly as documented, for example /v1/text-cleaner.

HTTP 415

unsupported_media_type

File type not accepted

The file you sent is not a type this tool accepts. Each tool lists the types it handles on its page.

Fix: Convert the file to an accepted type, or use the tool built for that format.

HTTP 422

malformed_upload

File failed validation

The upload did not survive structural checks — its contents did not match the type it claimed, it was an archive or executable, or text was not valid UTF-8. Archives and executables are never accepted.

Fix: Send the file itself rather than an archive of it, and make sure the type you declare matches the actual contents.

HTTP 413

input_too_large

Input too large

The request body exceeded the maximum input size for the endpoint.

Fix: Split the input, or check the endpoint page for its documented maximum.

HTTP 422

processing_failed

File could not be processed

The file was an accepted type and survived validation, but the tool could not read it — a truncated PDF, an image with a broken data stream, a media file the decoder rejects. You sent the right kind of thing and it was damaged.

Fix: Open the file locally to confirm it is intact, re-export it from the application that produced it, and try again.

HTTP 404

unknown_operation

No such operation

The path named a tool this service does not host. Because routes and tools are generated from one registry, this only appears during a partial deploy.

Fix: Check the path against the catalogue. If a tool listed as live returns this, it is our bug — the request id identifies it in our logs.

HTTP 500

internal_error

Something went wrong at our end

The tool raised an error we did not anticipate. The detail is deliberately withheld from the response and written to our logs instead, because this API serves anonymous callers.

Fix: Retry once. If it persists, quote the request id from the response — it is the key to the log entry.

HTTP 422

invalid_input

Invalid input

The body was not valid JSON, a required field was missing, or a field had the wrong type.

Fix: Check the required fields on the endpoint page. Note that a rejected body still costs a credit — validation happens after authorisation.