For developers

Tekomata API

Read a photo or PDF into data with the AI model of your choice, in a standard form, with the page and the place on the document where each value was read; write blog posts with AI, and hear when each is done by webhook. Read the balance and top it up by bank transfer. Paid from the shop's Tekomata credit — try it below with your integration's access token.

Errors and limits

Every error has the same shape: {"error": {"code": "…", "message": "…"}}. The code does not change; the sentence is for people to read, always in English, and may change.

HTTPcodeMeaning
400malformed, malformed_json, invalid_idempotency_keyThe request body cannot be read, or the Idempotency-Key is not 1 to 255 characters.
401api_credentials_required, invalid_api_key, access_token_required, invalid_access_token, access_token_expiredNo access token (api_credentials_required); the client ID and secret were sent in place of an access token (access_token_required, both only for POST /v1/token); or the token is wrong, revoked, or expired. Request a new token.
402insufficient_credit, queue_full, not_on_planThe shop's balance is not enough for this or for the queue of reads already waiting (top up first), or the shop's plan does not include the API.
403missing_scope, not_available_to_api, scan_offThis integration does not have the permission, that part is not open to the API, or AI scanning is not switched on on this server.
404not_foundDoes not exist, or belongs to another shop.
409too_many_pending, already_reported, already_decided, top_up_cancelled, read_in_progress, type_off, duplicate_name, idempotency_request_in_progressThe current state does not allow that request now, or the first request with the same Idempotency-Key is still being answered.
422invalid, model_not_offered, file_kind, no_fields, pdf_too_many_pages, pdf_unreadable, page_out_of_range, over_max_charge, document_keeps_failing, too_many_pages, knowledge_full, invalid_amount, idempotency_key_reused, event_not_allowedThe request content is wrong. The message says what needs fixing.
429rate_limited, too_many_running, too_many_failures, scan_limitOver the per-minute request limit (wait as long as Retry-After says), 10 articles being written or 10 images being made, too many failed reads today, or today's 20 scans are used up.
503ai_unavailable, no_model, top_up_unavailable, secrets_key_missingNo AI model can be used, top-ups are not available yet, or this server cannot sign webhooks yet.
  • The per-minute request limit is set by the shop per integration (default 60). Every response carries X-RateLimit-Limit and X-RateLimit-Remaining.
  • An access token is valid for 15 minutes.
  • The response for an Idempotency-Key is kept for at least 24 hours; 5xx responses are not kept, so a retry runs again.