GeniffyDocs
Changelog Log In Get a key

Errors and limits

Every error the API can return, what to do about it, and every limit, read from the server.

The shape of an error

Every error is JSON with a code you can branch on and a sentence written for a person:

{ "error": { "code": "bad_space", "message": "A space is up to 128 letters, digits, dots, dashes or underscores, and starts with a letter or a digit." } }
Status Code When
401 bad_key No key, a malformed key, or a key that was revoked
402 allowance_used What waits to be learned has reached ten months of your plan's learning (fair use). Past your plan, saves are kept, found by search and learned when the month resets, with no error; this one comes only at that limit. Saving resumes when the month resets (GET /v1/usage says when), at once with extra learning on, or on a bigger plan; reading keeps working. See Plans and usage
403 wrong_key A key that is not a personal Geniffy key
409 saving_paused Saving is paused for your own memory (Settings, Your data). Nothing sent while it is paused is kept, and nothing is sent later; reading keeps working, and your app's users' spaces are never paused
403 out_of_scope The key cannot reach that memory
404 not_found No memory or source with that id, or no file at that path, in that space
404 not_switched_on The briefing and where-things-stand doors, on a deployment where they are switched off
409 busy Another call is changing the same external_id at that moment, or deleted a file while it was being written; send it again
409 deleted The source was deleted while this call was saving it; nothing from the call was kept
409 conflict A file is already at a path a move would take; nothing moved
413 too_large A file over 25 MB
422 invalid_request A field missing or out of range; the message names it
422 bad_space A space name with characters a space cannot have, or a space that is named but blank
422 bad_kind A kind other than people, plan, pref or detail
422 bad_said_at A said_at that isn't an ISO 8601 date or time, or isn't in the past (no earlier than 1970)
422 bad_external_id An external_id that is blank, longer than 300 characters, or holds a line break; or, on an add, one that starts with file:, which only files use
422 bad_path A file's path or a prefix outside the rules
422 bad_labels Labels or a label filter outside the rules
422 empty Nothing to add, or nothing to ask
422 unreadable A file or page that could not be read, with the reason
422 too_many A conversation of more than 500 messages in one call; send the rest in another, under a session to keep them one memory
429 busy Too many requests at once; try again shortly
502 memory_unavailable The memory did not answer in time; try again
503 not_ready The service is starting; try again shortly
503 labels_unavailable Labels sent while the memory service is being updated; nothing was saved or read with them, so try again shortly

The SDKs raise these as typed errors: AuthenticationError, NotFoundError, BadRequestError, UnreadableError, UsageLimitError (402, never retried), RateLimitError, InternalServerError and APIConnectionError.

Retries

The SDKs retry reads twice on a network error, 408, 429 and 5xx, waiting a little longer each time and honouring Retry-After. Putting a file is retried the same way, since the same text sent twice is the same file. Adding is retried only when the request never reached Geniffy, or on 429, so a retry never saves a note twice. Change it with max_retries and timeout (Python) or maxRetries and timeout (TypeScript) on the client.

Limits

What Limit
A note 2,000,000 characters
A file kept under a path 2,000,000 characters of text, under a path of up to 255 characters
A file 25 MB and 2 million characters; PDF, Word .docx, PowerPoint .pptx, Excel .xlsx, or text (.txt, .md, .csv, .tsv, .html); unpacked, Word and PowerPoint up to 10 MB of text and layout, Excel 20 MB; a saved .html page 2 MB; a scan with no text layer is refused, never guessed at
A web page Public addresses only, 5 MB; a link to a PDF is read as a PDF
A batch Up to 100 items
A conversation Up to 500 messages in one call
A question 2,000 characters
context limit 1 to 50 memories, default 12
search limit 1 to 50 memories, default 10
Files listed 1 to 200 a page, default 100; a delete by prefix takes up to 100 a call
A space name 128 characters
Requests from one address 30,000 in 5 minutes; past that, 429 busy with Retry-After

Request ids

Every response carries an X-Request-ID, and every SDK error carries it. See Request ids for finding any call again.

Last updated October 17, 2026