Error reference
Every error from a Grupr API is JSON with a short code you can branch on. This page explains the three people look up by name, 402 budget_exceeded, 403 model_not_allowed and 429 sandbox_budget, and the plan limit codes such as 402 sandbox_allowance_used and 402 overage_cap_reached, and the settings and checkout codes: what causes each, what the response looks like, and how to clear it.
The two response shapes#
The agent hub, the Analytics read API and the rest of api.grupr.ai/api answer with an errors array:
{
"errors": [
{ "code": "forbidden", "message": "Agent is not assigned to this grupr" }
]
}A validation error adds field, naming the input that was wrong. A 429 rate_limited adds retry_after_seconds and sends the same number in a Retry-After header. The routes behind the Grupr Analytics screens of the web app (under /api/analytics/) are the exception: they answer with one object, its error field holding the message and, on some errors, a code beside it (see invalid_usage_retention).
The gateway is different on purpose. It stands in for a model provider, so it answers in that provider's error format and existing OpenAI and Anthropic clients can read it:
| Gateway route | Error body |
|---|---|
POST /api/gateway/v1/chat/completions (OpenAI-compatible) | {"error": {"message": "...", "type": "..."}} |
POST /api/gateway/anthropic/v1/messages (Anthropic-compatible) | {"type": "error", "error": {"type": "invalid_request_error", "message": "..."}} |
402 budget_exceeded#
What it means: the virtual key you called the gateway with has reached its monthly spending cap, so the request was refused before it reached the model provider. No model call was made.
Cause#
- The key (
gvk_…) was created with a monthly cap in US dollars. A key with no cap never returns this error. - The gateway adds up what the key has spent through the gateway since 00:00 UTC on the first of the month, plus the requests it has in flight right now, and compares that with the cap plus any approved overage.
- Once the total reaches that figure, every request on the key gets a
402until the cap is raised or the month ends.
Response#
From the OpenAI-compatible route. The message states the amount used and the cap, and names the route that asks for more; the dollar figures below are an example.
HTTP/1.1 402 Payment Required
Content-Type: application/json
{
"error": {
"message": "monthly budget exceeded for this key: $250.00 of $250.00 used this month. Request a temporary overage: POST /api/gateway/v1/overage-request with this key (body: {\"amount_usd\":N,\"reason\":\"...\"}) or ask an org admin",
"type": "budget_exceeded"
}
}The Anthropic-compatible route refuses the same request with the same 402 status and the same message, but in Anthropic's envelope, where error.type is invalid_request_error. The string budget_exceeded appears only on the OpenAI-compatible route, so on the Anthropic route branch on the status code.
How to fix it#
- Ask for a temporary overage with the same key. Send the amount and a reason:
If your department has an auto-approve limit and the amount is inside it, the answer iscurl -X POST https://api.grupr.ai/api/gateway/v1/overage-request \ -H "Authorization: Bearer $GRUPR_VIRTUAL_KEY" \ -H "Content-Type: application/json" \ -d '{"amount_usd": 50, "reason": "Release week"}'201with"status": "approved"and the raise lasts until the end of the month. Otherwise the answer is202with"status": "pending": the organization's admins and finance members are emailed and one of them approves or declines it in Grupr Analytics. A second request while one is pending gets409with typeoverage_pending. - Ask an org admin. A key's cap is set when the key is created. To change it for good, an admin issues a new key with the cap you need and revokes the old one.
- Wait for the month to turn. Spend is counted per calendar month in UTC, so the key works again at 00:00 UTC on the first.
Do not retry in a loop: the answer does not change until one of those three things happens. To see how close a key is before it is refused, read spend_mtd_usd and the cap from the budgets endpoint of the Analytics read API.
403 model_not_allowed#
What it means: the virtual key you called the gateway with is limited to a list of models, and the model named in the request is not on it.
Cause#
- A key can be created with an allow-list of model ids. An empty list means any model.
- The gateway compares the request body's
modelwith that list before it forwards anything. The match is on the exact id, so a dated or aliased variant of an allowed model is refused too.
Response#
From the OpenAI-compatible route; the message ends with the model you asked for.
HTTP/1.1 403 Forbidden
Content-Type: application/json
{
"error": {
"message": "model not permitted for this key: gpt-5.1",
"type": "model_not_allowed"
}
}On the Anthropic-compatible route the status is also 403 and the message is the same, with error.type set to invalid_request_error.
How to fix it#
- Use a model the key allows. Change the
modelin the request to one on the key's list, spelled exactly as listed. - Ask an org admin for a key that allows the model. The allow-list is set when a key is created; the admin issues a new key that includes the model (or has no list) and revokes the old one.
A 400 with unknown model is a different problem: the id is not in Grupr's model catalog at all, whatever the key allows.
429 sandbox_budget#
What it means: an agent tried to use its workspace after using up the daily sandbox time its owner allows. The call was not run.
Cause#
- An agent's owner can set a daily sandbox budget on the agent page, from 5 minutes to 24 hours per UTC day. An agent with no budget never gets this error.
- Sandbox time is counted from the moment the workspace starts or resumes until it pauses. When today's total reaches the budget, the agent's commands and file operations are refused with this error, and its routines are recorded as skipped.
Response#
From the agent hub workspace routes, for example POST /api/v1/agent-hub/workspace/run. The message gives minutes used and the budget; the figures below are an example.
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
{
"errors": [
{
"code": "sandbox_budget",
"message": "The agent's daily sandbox budget is used up (30 of 30 min). Its commands, routines and file operations wait until 00:00 UTC; the owner can raise the budget on the agent page."
}
]
}How to fix it#
- Wait until 00:00 UTC. The count starts again each UTC day.
- Have the owner raise or clear the budget on the agent page in the app. The agent cannot change its own budget.
This is not the ordinary rate limit, so backing off for a few seconds does not help: there is no Retry-After header on it. An agent can see it coming by reading sandbox_budget_seconds, sandbox_budget_exhausted and sandbox_budget_resets_at from GET /api/v1/agent-hub/workspace; the agent usage report guide shows how. The owner's own console and file browser keep working while the agent waits.
Plan limit codes#
Each plan includes sandbox time and Agent Mail by the month, an amount of storage and a number of outside agents (plans and limits). When a request would go past one, Grupr refuses it before doing the work and nothing is charged. These codes come in the usual errors array. A refusal about a quantity (the sandbox, Agent Mail, storage and overage codes, agent_limit, trial_exhausted and analytics_plan_required) also says how much was used, the allowance and its unit (seconds, emails, bytes, agents, reviews or organizations). resets_at (00:00 UTC on the 1st) appears only where the month turning helps: on sandbox_allowance_used and sandbox_needs_reset on Solo, Pro and Team, on agent_mail_allowance_used on Solo, Pro and Team, and on overage_cap_reached whatever raised it. It never appears on sandbox_needs_key, storage_allowance_used, agent_limit, the E2B key codes, the trial codes, analytics_plan_required or a trial's sandbox refusals (the trial's 30 minutes cover the whole trial and do not come back on the 1st), because what frees them is a key, a plan, deleting or a person, not the calendar. Read resets_at when it is there and do not require it:
HTTP/1.1 402 Payment Required
Content-Type: application/json
{
"errors": [
{
"code": "sandbox_allowance_used",
"message": "This month's sandbox time on your plan is used up. Add your own E2B key in Settings, API Keys, turn on overage in Settings, Plan and usage, or upgrade.",
"used": 28800,
"allowance": 28800,
"unit": "seconds",
"resets_at": "2026-12-01T00:00:00Z"
}
]
}The message is written for a person and is shown as is in the app. It depends on the plan: overage is offered only on Solo, Pro and Team, so a free or trial account is told about its own key or subscribing instead. The messages below are the ones in use; branch on the code, not the text. When the refused work was running in the background (a routine firing, a Grupr Build iteration, a Deep review patch), the same message is recorded where that job reports a refusal: a room note, an item in Waiting on you, or the run's status. Three codes only ever appear that way, on a room note or a review's failure and not as an HTTP response: trial_room_reply_needs_key, trial_spend_no_room and trial_spend_unavailable.
In the web app, the screens these messages name are Settings, API Keys (your model keys and the E2B sandbox key) and Settings, Plan and usage (what your plan includes, what you have used this month, and the overage switch and cap).
402 sandbox_needs_key#
What it means: the account is on the free plan, which includes no sandbox time paid for by Grupr, and it has no E2B key of its own. Anything that needs a sandbox is refused: an agent's workspace command or file operation, a routine, the console on an agent's page, a Deep review patch, Verified PR, a Grupr Build run.
Message: “The free plan has no Grupr-paid sandbox time. Add your own E2B key in Settings, API Keys, or start the Solo trial.” An account that can no longer start a trial gets the message without the trial: “The free plan has no Grupr-paid sandbox time. Add your own E2B key in Settings, API Keys.”
How to fix it: add your own E2B API key in Settings, API Keys (how it works); your sandboxes then run on your E2B account. Or start the Solo trial if the account can still have one, or subscribe to a paid plan.
402 sandbox_allowance_used#
What it means: the account has used this month's sandbox time on its plan (on the trial, its 30 minutes, which cover the whole trial rather than a month), and overage is off. Every sandbox Grupr pays for counts toward it, not only agent workspaces. With overage on, the code past the cap is overage_cap_reached instead.
Message on Solo: “This month's sandbox time on your plan is used up. Add your own E2B key in Settings, API Keys, turn on overage in Settings, Plan and usage, or upgrade.”
Message on Pro: “This month's sandbox time on your plan is used up. Add your own E2B key in Settings, API Keys, turn on overage in Settings, Plan and usage, or move to Team.”
Message on Team: “This month's sandbox time on your plan is used up. Add your own E2B key in Settings, API Keys, or turn on overage in Settings, Plan and usage.”
Message on the trial: “Your trial's sandbox time is used up. Add your own E2B key in Settings, API Keys, or keep going when your Solo plan starts at the end of the trial.”
On a plan with no overage (a Solo, Pro or Team plan bought in the App Store, or a complimentary one; see overage_not_available), the sentence does not offer overage. Solo: “This month's sandbox time on your plan is used up. Add your own E2B key in Settings, API Keys, or upgrade.” Pro: “This month's sandbox time on your plan is used up. Add your own E2B key in Settings, API Keys, or move to Team.” Team: “This month's sandbox time on your plan is used up. Add your own E2B key in Settings, API Keys, or email sales@grupr.ai to add seats.”
How to fix it: add your own E2B key (new sandboxes on it are never refused for the allowance; a workspace started before the key gets sandbox_needs_reset instead); on Solo, Pro and Team, turn on overage in Settings, Plan and usage with a cap; move to a larger plan (email sales@grupr.ai to switch plans, or on Team to add seats); or wait for resets_at. On the trial there is no resets_at: the trial's time does not come back on the 1st, and a trialing account cannot start a second subscription (checkout answers 409 subscription_already_active). Add your own E2B key, or wait for the trial to become paid Solo when its two days end (unless you cancel), with Solo's monthly sandbox time.
402 sandbox_needs_reset#
What it means: the account has its own E2B key, but this agent's workspace was started on Grupr's E2B account before the key was added. A workspace stays on the account it started on, so it still runs on the plan's sandbox time, and that time is used up. Only that workspace is refused; new sandboxes run on your key. Grupr does not move it for you, because moving it would lose its files.
Message: “This agent's workspace runs on Grupr's sandbox time, which your plan does not cover now; press Reset workspace on the agent page to restart it on your own E2B key (its files are not kept).”
How to fix it: press Reset workspace on the agent page. The workspace restarts on your E2B key; its files are not kept, so download anything you need first. Or, on Solo, Pro and Team, turn on overage, or wait for resets_at (not on the trial, which has none).
402 e2b_key_rejected#
What it means: the account has its own E2B key and E2B would not start or reach a sandbox with it, usually because the key was revoked or replaced at E2B after you saved it. Nothing runs on Grupr's account instead.
Message: “E2B rejected your own E2B key; update it in Settings.”
When you save a key: Grupr checks a new E2B key with E2B before it stores it. A key E2B rejects is refused with 400 and this code (field is api_key), and is not saved: “E2B rejected this key. Copy it again from the API Keys page of your E2B dashboard.”
How to fix it: save a working E2B API key in Settings, API Keys, or remove the key to go back to your plan's sandbox time.
502 e2b_unreachable#
What it means: you saved an E2B key and Grupr could not reach E2B to check it. The key is not saved. This comes only from saving a key, not from running a sandbox.
Message: “Could not reach E2B to check this key. Try again in a minute.”
How to fix it: save the key again in a minute.
402 agent_mail_allowance_used#
What it means: sending this email would take the account past its plan's Agent Mail for the month. Each recipient (To and Cc) counts as one email, so a message to three people needs three. The free plan and the trial include no Agent Mail, so every send there gets this code. The email is not sent.
Message on Solo and Pro: “This month's Agent Mail on your plan is used up. Turn on overage in Settings, Plan and usage, or upgrade.”
Message on Team: “This month's Agent Mail on your plan is used up. Turn on overage in Settings, Plan and usage, or email sales@grupr.ai to add seats.”
Message on the free plan: “Agent Mail is not included on the free plan. Subscribe to Solo to send mail from your agents.”
Message on the trial: “Agent Mail is not included in the trial. It starts with your Solo plan when the trial ends.”
On a plan with no overage (bought in the App Store, or complimentary): Solo and Pro, “This month's Agent Mail on your plan is used up. Upgrade, or wait until the 1st.” Team, “This month's Agent Mail on your plan is used up. Email sales@grupr.ai to add seats, or wait until the 1st.”
How to fix it: on Solo, Pro and Team, turn on overage in Settings, Plan and usage, move to a larger plan (email sales@grupr.ai to switch plans, or on Team to add seats), or wait for resets_at. On the free plan, subscribe to Solo. On the trial, Agent Mail starts when the trial becomes paid Solo at the end of its two days, unless you cancel; a trialing account cannot start a second subscription. The per-agent daily limits on the AgentOS page apply as well.
402 storage_allowance_used#
What it means: the upload (a Room File, an attachment, a file an agent publishes, a document it writes) would take the account over its plan's storage. Storage counts the Room Files, with their kept versions, and documents in every room the account owns. Nothing is written.
Message on Solo and Pro: “This upload would go over your plan's storage. Delete files, turn on overage in Settings, Plan and usage, or upgrade.”
Message on Team: “This upload would go over your plan's storage. Delete files, turn on overage in Settings, Plan and usage, or email sales@grupr.ai to add seats.”
Message on the free plan: “This upload would go over your plan's storage. Delete files or subscribe to a plan with more storage.”
Message on the trial: “This upload would go over your plan's storage. Delete files to make room.”
On a plan with no overage (bought in the App Store, or complimentary): Solo and Pro, “This upload would go over your plan's storage. Delete files or upgrade.” Team, “This upload would go over your plan's storage. Delete files or email sales@grupr.ai to add seats.”
How to fix it: delete files you no longer need (older versions count too), turn on overage in Settings, Plan and usage (Solo, Pro and Team), or move to a larger plan (email sales@grupr.ai to switch plans, or on Team to add seats; on the free plan, subscribe). Unlike sandbox time and Agent Mail, storage does not free itself on the 1st, so the response has no resets_at. If you turn overage on to store more, you cannot turn it off again while the files are over the allowance (409 storage_over_allowance).
402 overage_cap_reached#
What it means: overage is on (Solo, Pro and Team) and this month's overage has reached the monthly cap you set, so the work past the allowance is refused just as it would be with overage off. It can come from anything that has an allowance: a sandbox, an email, an upload. The entry carries used, allowance and unit of the allowance that ran out (seconds, emails or bytes), and resets_at, when the month's overage count starts again.
Message: “This month's overage reached the cap you set. Raise the cap in Settings, Plan and usage, or wait until the 1st.”
How to fix it: raise the cap in Settings, Plan and usage (up to $1,000 a month), add your own E2B key for sandbox time, delete files for storage, or wait until 00:00 UTC on the 1st, when the allowance and the overage count start again.
409 agent_limit#
What it means: the account already owns as many outside agents as its plan allows (3 on Free, 10 on Solo and during the trial, 25 on Pro, 25 per seat on Team). The entry carries used (the outside agents the account has), allowance (the plan's number) and unit agents, and no resets_at. The message names the plan and its limit, for example “Your Solo plan includes 10 outside agents. Delete one you no longer use to add another, or upgrade for more.”
On Pro the message says “or move to Team for more”, and on Team “or add seats for more”.
How to fix it: delete an outside agent you no longer use, or move to a larger plan (from the free plan, subscribe; to switch a paid plan, or on Team to add seats, email sales@grupr.ai).
409 trial_already_used#
What it means: you asked to start the Solo trial, and Grupr already knows that this account, or its card, has had a Grupr trial. There is one trial per card and per account. No trial starts and nothing is charged.
Message: “This account or card has already had a Grupr trial. Subscribe to Solo to continue.”
How to fix it: subscribe to Solo without a trial. If only the card has had a trial, Grupr learns that at checkout: the new trial is cancelled straight away and never charged, and the app says so and offers Solo without a trial (see the trial).
402 trial_exhausted#
What it means: during the Solo trial, you started a review that would run on Grupr's keys, and the trial's included reviews of that kind are used up: the trial includes 2 Quick reviews and 1 Deep review. Nothing starts. The entry carries used, allowance and unit reviews, and no resets_at.
Message: “Your trial's included reviews on Grupr's keys are used up. Add your own model keys in Settings, API Keys to keep reviewing.”
How to fix it: add your own Anthropic and OpenAI keys in Settings, API Keys. Reviews then run on those keys and the trial's review allowance does not apply. Subscribing does not bring back reviews on Grupr's keys: a trialing account cannot start a second subscription (checkout answers 409 subscription_already_active), the trial becomes paid Solo by itself when its two days end unless you cancel, and Solo's reviews run on your own keys too.
402 trial_expired#
What it means: a review was started on Grupr's keys after the account's Solo trial ended but before Grupr had moved the account off the trial (for example, in the moments before Stripe reports the trial's end). Reviews on Grupr's keys are part of the trial only. Nothing starts. Once the account has moved on, to paid Solo or, after a cancelled trial, to the free plan, a review follows that plan instead of getting this code: it runs on your own model keys (on the free plan, one Quick or Smart review a day).
Message: “Your trial has ended. Subscribe to Solo, or add your own model keys and keep going on the free plan.”
How to fix it: add your own model keys in Settings, API Keys and carry on with the free plan's one Quick or Smart review a day, or subscribe to Solo (its reviews also run on your own keys).
trial_room_reply_needs_key (room note)#
What it means: during the Solo trial, an agent's reply in a room would have run on Grupr's model keys. Grupr's keys pay only for the trial's reviews, not for room chat, so the reply is not made. This is not an HTTP error: posting your message still succeeds. The agent's turn is skipped and the room shows a note, “agent (provider) was skipped:” followed by the message below; the agent_response_complete event on the WebSocket stream carries the code in its code field.
Message: “During the trial, room replies need your own model key. Add one in Settings, API Keys.”
How to fix it: add a key for the agent's model provider in Settings, API Keys.
402 trial_spend_cap_reached#
What it means: the trial's reviews on Grupr's keys have reached their cost limit, $1.00 of model calls in all. Starting a review then answers 402 with this code in the errors array. If the limit is reached while a review runs, the reviewer is skipped with a room note, or the Deep patch fails, with the same message.
Message: “Your trial's included reviews on Grupr's keys are used up. Add your own model keys in Settings to keep going.”
How to fix it: add your own Anthropic and OpenAI keys in Settings, API Keys; reviews then run on those keys for the rest of the trial and after it.
trial_spend_no_room (room note)#
What it means: the trial's spend on Grupr's keys is still under $1.00, but what is left is too small for this reviewer's call on this much code, so the call does not start. It appears on a reviewer's room note or as a Deep patch's failure, not as an HTTP response.
Message: “What is left of your trial's included use of Grupr's keys is too small for this reviewer on this much code. Add your own model keys in Settings, or review a smaller piece of code.”
How to fix it: add your own model keys in Settings, API Keys, or review a smaller piece of code.
trial_spend_unavailable (room note)#
What it means: Grupr could not read the trial's usage of its keys just then, so it ran nothing on them: Grupr never makes a call on its keys that it cannot count. It appears on an agent's or reviewer's room note or as a review's failure, not as an HTTP response, with one message wherever it appears.
Message: “Grupr could not check this trial's usage just now. Try again in a minute, or add your own model keys in Settings, API Keys.”
How to fix it: try again in a minute, or add your own model keys in Settings, API Keys.
402 analytics_plan_required#
What it means: the account tried to create a Grupr Analytics organization, and it has no Analytics plan. Organizations are set up by Grupr's team. The entry has used and allowance of 0 and unit organizations.
Message: “Grupr Analytics is set up by our team. Email sales@grupr.ai to start.”
How to fix it: email sales@grupr.ai.
Settings and checkout codes#
These come from changing a setting or starting a purchase, not from running out of an allowance. Nothing is charged when one of them is returned.
Turning overage on or off: PUT /api/overage#
The overage switch and cap in Settings, Plan and usage are saved with PUT /api/overage, body {"enabled": true, "monthly_cap_cents": 2500, "consent_text_version": "v1"}. It answers these errors in the errors array; the setting is not changed.
| Status and code | When | Message |
|---|---|---|
400 validation_error | The body is not valid JSON | “Invalid JSON body” |
400 validation_error, field enabled | The body does not say whether overage is on | “Say whether overage is on (enabled).” |
400 validation_error, field monthly_cap_cents | Turning overage on without a cap, or a cap that is not whole dollars from $5 to $1,000 (500 to 100000 cents) | “Set a monthly cap in whole dollars, from $5 to $1,000.” |
400 validation_error, field consent_text_version | Turning overage on without agreeing to the overage charges | “Agree to the overage charges to turn overage on.” |
| 403 overage_not_available | Turning overage on where the account cannot have it | “Overage is available on Solo, Pro and Team plans paid by card at grupr.ai. Plans bought in the App Store and complimentary plans have no overage.” |
| 409 storage_over_allowance | Turning overage off while the files you store are over your plan's storage | “Your files are over your plan's storage. Delete files to get under 1 GB before turning overage off.” (with your plan's storage) |
500 server_error | Grupr could not save the setting, or could not read how much you store when you turn overage off (it is never turned off on a guess) | “Could not save your overage setting. Try again in a minute.” |
503 billing_unavailable | Turning overage on while billing is not available on Grupr's side | “Billing is not available right now. Try again later.” |
Retry a 500 or 503 later; the others need a change to the request or to your files. Turning overage off stops sandbox and Agent Mail overage at once; what was already recorded is still billed. Overage is billed after the month ends, on a later invoice for your plan, usually the next one; if your plan ends before then, Grupr bills it separately (how overage works).
409 storage_over_allowance#
What it means: you tried to turn overage off while it is on and the files you store are over your plan's storage. Storage past the allowance is kept only while overage pays for it, and files stay until you delete them, so Grupr refuses and overage stays on. Sandbox time and Agent Mail have no such rule. The entry carries used (the bytes you store now), allowance (your plan's storage in bytes) and unit bytes, and no resets_at: storage does not free itself on the 1st.
HTTP/1.1 409 Conflict
Content-Type: application/json
{
"errors": [
{
"code": "storage_over_allowance",
"message": "Your files are over your plan's storage. Delete files to get under 1 GB before turning overage off.",
"used": 1288490189,
"allowance": 1073741824,
"unit": "bytes"
}
]
}Message: “Your files are over your plan's storage. Delete files to get under allowance before turning overage off.” The allowance is written in binary units, as the plans are (1 GB is 1,073,741,824 bytes): “1 GB” on Solo, “3 GB” on Pro, and on Team 3 GB a seat, such as “15 GB” with five seats.
How to fix it: delete files (older versions count too) until used is at or under allowance, then turn overage off. Settings, Plan and usage shows your storage against the allowance.
403 overage_not_available#
What it means: you tried to turn overage on, and the account cannot have it. Overage is offered only on Solo, Pro and Team paid by card through Grupr's checkout. The free plan and the trial do not have it, and neither does a Solo, Pro or Team plan bought in the App Store or a complimentary plan (one Grupr gives an account, with no card subscription to bill): their refusals offer no overage either (see sandbox_allowance_used, agent_mail_allowance_used and storage_allowance_used).
Message: “Overage is available on Solo, Pro and Team plans paid by card at grupr.ai. Plans bought in the App Store and complimentary plans have no overage.”
How to fix it: on the free plan, subscribe to Solo or Pro by card, or ask sales@grupr.ai about Team. During the trial, overage becomes available once the trial has become paid Solo. A plan bought in the App Store or a complimentary plan stops at its allowances. For sandbox time beyond any plan's allowance, your own E2B key works on every plan.
409 subscription_already_active#
What it means: you started a checkout for an account that already has a Grupr subscription. An account has one subscription, so no checkout opens and nothing is charged. The message says where the existing subscription is managed:
- Paid by card (a subscription that is not over: active, on its trial, past due, unpaid, incomplete or paused): “This account already has a Grupr subscription. Manage it in Settings.”
- Through the App Store: “This account already has a Grupr subscription through the App Store. Manage it in your Apple account's subscriptions.”
Starting the Solo trial answers the same code. On an account whose plan is already active (by card or through the App Store), the message is “You already have an active subscription. Manage it from Settings.” A card subscription that stands without being active (past due, unpaid, incomplete or paused) gets the card sentence above, unless the account has already had a trial (then 409 trial_already_used).
An App Store purchase in the iOS app on an account that already pays by card answers the same code too: “This account already has a Grupr subscription paid by card, so this App Store purchase was not applied to it. Contact support@grupr.ai if you were charged.”
How to fix it: manage the existing subscription where the message says: card, invoices and cancelling in Settings, an App Store subscription in your Apple account. To move between plans, email sales@grupr.ai. During the Solo trial there is nothing to buy: the trial becomes paid Solo when its two days end, unless you cancel.
409 trial_already_active#
What it means: you asked to start the Solo trial while this account's trial is already running (for example, a second click on the link that starts it). No second trial starts and nothing is charged.
Message: “Your trial is already active. Visit Settings to manage it.”
How to fix it: nothing to fix: the trial you have is running. Manage or cancel it in Settings.
400 invalid_usage_retention#
What it means: an Analytics admin saved data governance settings for an organization (PUT /api/analytics/orgs/{orgID}/settings) with a usage retention the organization's plan does not allow. Usage data is kept for 13 months (395 days) by default. An organization can choose a shorter period, from 1 to 395 days; keeping it longer, or forever, needs extended retention arranged with Grupr, which allows 1 to 3650 days or no limit. A legal hold is always allowed and is not affected. Nothing is saved.
Response: this route uses the Analytics shape, one object with the message in error, and adds max_usage_retention_days, the longest period the organization may set (395, or 3650 with extended retention):
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "Your plan keeps usage data for at most 395 days (13 months). Set usage_retention_days to a number from 1 to 395. Longer retention is arranged with our team: sales@grupr.ai.",
"code": "invalid_usage_retention",
"max_usage_retention_days": 395
}That message is the one for a period over 395 days, or no limit (null), without extended retention. A number below 1 or above 3650 gets “usage_retention_days must be 1 to 3650 days.” whatever the plan.
How to fix it: set usage_retention_days to a number from 1 to max_usage_retention_days. For longer retention, email sales@grupr.ai.
400 invalid_content_retention#
What it means: the same data governance settings route was sent a content_retention_days below 1 or above 3650. Nothing is saved. The body is the Analytics shape, with the message in error and the code beside it.
Message: “content_retention_days must be 1 to 3650 days, or null for no content window.”
How to fix it: send a number from 1 to 3650, or null.
Agent hub codes#
The codes an agent meets on the agent hub HTTP API:
| Status | Code | When |
|---|---|---|
| 400 | invalid_body | The request body is not valid JSON |
| 400 | validation_error | A required input is missing or malformed; field names it |
| 401 | unauthorized | No token, a token in the wrong format, or one that is revoked or expired |
| 403 | forbidden | The agent is not in that room, or the resource belongs to someone else |
| 404 | not_found, no_webhook | The thing does not exist; no_webhook when a webhook test finds none registered |
| 402 | sandbox_needs_key, sandbox_allowance_used, sandbox_needs_reset, e2b_key_rejected, agent_mail_allowance_used, storage_allowance_used, overage_cap_reached | The owner's plan allowance (or overage cap) is used up, or their own E2B key needs attention (above) |
| 429 | rate_limited | Too many requests in a minute; wait retry_after_seconds |
| 429 | sandbox_budget | The daily sandbox budget is used up (above) |
| 500 | server_error | Something failed on Grupr's side; safe to retry later |
| 503 | unavailable | A feature the route needs is not enabled on the server |
The Analytics read API has its own short list on its page.
Handling errors well#
- Branch on the status and the code, not on the message text. Messages are written for people and can change.
- Retry
429 rate_limitedand5xx(including502 e2b_unreachable) with a delay. Do not retry400,402,403,409 agent_limit,409 trial_already_used,409 trial_already_active,409 subscription_already_active,409 storage_over_allowanceor429 sandbox_budgetunchanged: each needs a person, a key, a setting, deleting files, a change to the request or the clock. - Something here wrong or missing? Write to support@grupr.ai and we will correct the page.
Last updated: