Reference
Errors and limits
What each status code means, the exact sentences, and how much you can do.
The shape of an error
Every response has an ok field. When a request is refused, ok is false and error is a sentence that says what went wrong and what to do about it. It is written to be shown to a person as it is.
{ "ok": false, "error": "No such app on this account." }There are no other fields on a refusal, with one exception: an edit that has started and then could not run for lack of credits also carries outOfCredits: true.
Status codes
| Status | Meaning | What to do |
|---|---|---|
200 | Done. For an edit, it has started and ok says how it ended. | Read ok. |
400 | Something in the request is missing or not allowed. | Fix the request, using error. |
401 | The key is missing, wrong or revoked. | Check the Authorization header and the key. |
402 | The call spends credits and cannot: the plan does not include it, or there are not enough credits. | Upgrade, or add credits, as error says. |
404 | There is no such app, or your key may not use it at the level the call needs. | Check the id with List your apps. |
409 | The app has no code yet, or, when publishing, its address cannot be used. | Build it in Setherion first, or read error. |
429 | A limit was reached. | Wait for it to reset. |
500 | Something failed on our side. | Try again. |
502 | Publishing failed on our side. | Try again. |
503 | A part of Setherion is briefly unavailable. | Try again in a minute. |
For privacy, "no such app" and "an app you may not use" give the same 404. Otherwise a key could be used to find out which apps exist. That includes an app you can only view when the call needs an editor.
Who may do what
Your role on the app decides which calls work:
| Role | Reads (list, store guide, privacy answers) | Changes and spends credits (edit, publish, store page) |
|---|---|---|
| Viewer | Yes | No, 404 |
| Editor | Yes | Yes |
| Admin, owner | Yes | Yes |
Limits
| What | Limit |
|---|---|
| Active API keys | 10 per account |
| Publishes through the API | 100 per account per day |
| Edits and builds | 120 per account per hour |
| Store pages written | Counted with the small AI actions of the account, 600 per hour |
| Length of an edit instruction | 4,000 characters |
Length of a search (q) | 100 characters |
| Apps returned by a list | 100 per page, the most recently changed first. See List your apps for the next page. |
| Time an edit may take | Up to about 13 minutes |
| Time a store page may take | Up to about 2 minutes |
The hourly limits are a pace, not an allowance. They are there for a script that runs faster than a person can, and nobody working by hand reaches them. What limits you in practice is your credits.
Edits are also limited by your credits and by your plan, exactly as in the editor. When an edit cannot run for that reason, the answer is 200 with ok: false and an error that says why. The store page is different: it has not started yet when it is refused, so it answers 402.
Which limit answers how
- Publish answers
429when the day's 100 are used, and503when the limiter itself cannot be reached. - Store page answers
429for the hour's limit,503when the limiter cannot be reached, and402for plan and credits. - Edit answers
200withok: false, anderrorcarries the sentence. The hourly one readsYou're working faster than our safety limit allows (120 an hour). You can carry on in about 12 minutes.
The sentences every call can answer
| Status | error |
|---|---|
401 | A valid API key is required. Make one on your Setherion account page and send it as "Authorization: Bearer sth_...". |
404 | No such app on this account. |
500 | The API is not configured on this server. |
The sentences of each call
- List your apps:
q is at most 100 characters.offset is a whole number, 0 or more.Could not list your apps. - Edit an app:
Say what to change, in "prompt".Keep "prompt" under 4,000 characters.This app has no code yet. Build it in Setherion first, then edit it here. - Publish an app:
That is 100 publishes through the API today. The count resets tomorrow.Publishing is briefly unavailable. Try again in a minute.Publishing through the API is not configured on this server.and the secret, address, private app and build sentences listed on its page. - App store readiness and Store privacy answers:
way is "easy" or "native".This app has no code yet. Build it in Setherion first. - Write the store page:
Writing the store page is part of the Pro plan.Too many AI actions in the last hour. Try again later.and the credit sentences listed on its page.
Was this page helpful?