Errors are always JSON, with the same shape everywhere:
{ "error": { "code": "forbidden", "message": "Only an owner can refund a live payment. This key has Limited access: ask a person to do it in the console, or to give the key full access.", "details": { "reason": "owner_only", "console_url": "https://thelastapi.dev/projects/prj_…/payments", "key_url": "https://thelastapi.dev/keys?key=key_…", "next_step": "Tell the user: the account owner does this in the console ▸ the project ▸ Payments ▸ the payment ▸ Refund (or with a full-access key). Retrying with this key will not work. Give the user this link, it opens the place to do it: https://thelastapi.dev/projects/prj_…/payments This key has Limited access. To let it do this from now on, the owner can give it full access in the console: https://thelastapi.dev/keys?key=key_… , or sign in again (vibiz login, or reconnect the MCP server) and choose Full access." } } }codeis stable: branch on it, never onmessage.messagesays what failed and why, in words to show a person as they are:Country: “SP” isn't a country code. Spain is ES., never a bare "something went wrong" when the reason is known.details.reasonrefines a code (owner_only,payouts_not_ready,daily_spend…).details.next_step, when present, is what to tell the person. Agents pass it on instead of retrying.details.console_url, when present, is the console page where it is fixed.- Every response has an
X-Request-Id; quote it to support. - AI routes add OpenAI's
typeandparamso OpenAI SDKs read them.
Codes
| Code | Status | Meaning | Next step |
|---|---|---|---|
invalid_request | 400 | The request is malformed or a field is wrong. details names the field (issues[].path, param, problems) | Fix the field; don't retry unchanged |
content_filtered | 400 | An AI content filter refused the request | Change the input |
context_length_exceeded | 400 | The AI input is longer than the model's window | Shorten it or use a larger model |
unauthorized | 401 | Missing, unknown or revoked key; an app key on an account route | Check the key and its kind |
forbidden | 403 | Not allowed for this key. With reason: owner_only: the key is Limited without details.permission | Give the person details.grant_url (allows that permission for this key, or everything) or details.console_url (do it themselves); retry once allowed |
no_account | 403 | Signed in to the console with no account yet | Create an account or link a key in the console |
not_found | 404 | No such object on this account or in this environment | Check the id and env |
conflict | 409 | The object's state doesn't allow it (details.reason says why), or a concurrent request with the same Idempotency-Key is still running | Read the object again; act on reason |
domain_taken | 409 | The slug or domain belongs to someone else | Pick another |
dependency_not_ready | 409 | A resource this needs is missing or still provisioning | Add it or wait, then retry |
insufficient_balance | 409 | The project's balance can't cover a refund | Wait for more sales, or refund less |
payment_required | 402 | The account is out of credits for a paid call (details.reason: insufficient_balance, or past_due for deploys after a week at zero) | Pass details.next_step and top_up_url to the person; don't retry until credits are added |
quota_exceeded | 413 | A stored quota is full (replay) | Delete or wait for retention |
payload_too_large | 413 | The body or upload is over its cap | Send less |
idempotency_mismatch | 422 | The same Idempotency-Key was used with a different body | Use a new key for a new request |
rate_limited | 429 | A limit was reached; details says which and resets_at | Wait (Retry-After or resets_at); don't loop |
client_outdated | 426 | The thelastapi CLI that called is older than the API supports; details.minimum | Update it: npm install -g @vibiz/cli@latest, then retry |
internal | 500 | Our bug | Retry once; then contact support with X-Request-Id |
provider_failed | 502 | The work was refused downstream (a refund refused; your own AI key rejected); message says why and details.refused_because carries the service's own reason when it gave one | Act on the reason; retrying unchanged rarely helps |
provider_unavailable | 503 | The service is unavailable right now, or the call timed out (details.reason) | Retry later with backoff |
model_unavailable | 503 | No route can run the model you asked for right now. thelastapi never swaps in another model | Retry after details.retry_after_seconds, or pick another model |
not_configured | 503 | This deployment doesn't offer that capability now | Use another model or capability |
Fields
A 400 invalid_request names every field that is wrong, and the rule it broke, in its message (name: must have at most 80 characters., or 3 fields need fixing: … for several). details carries the same for forms:
{ "error": { "code": "invalid_request", "message": "Country: “SP” isn't a country code. Spain is ES.", "details": { "field": "contact.country", "fields": ["contact.country"], "problems": [{ "field": "contact.country", "message": "Country: “SP” isn't a country code. Spain is ES." }], "issues": [{ "path": "contact.country", "message": "“SP” isn't a country code. Spain is ES." }] } } }fieldis the first field (a dotted path into the body, or the query parameter),fieldsall of them.problems[]is{ field, message }, the message naming the field: show each under its field.issues[]is{ path, message }without the field's name, for older clients.
When a service refuses
When a service thelastapi works with refuses something on its merits (a name a registry won't take, a value it rejects), the error says what it said, in its own words but never its name, links or ids: provider_failed with The request was refused: <reason>. and the reason alone in details.refused_because. Where the reason is about one of your fields, the error is invalid_request with that field instead. With no reason given, the message says so: write to support@vibiz.ai with the X-Request-Id.
Retries and idempotency
Any POST accepts Idempotency-Key. The first successful JSON response is stored for 24 hours and replayed for a retry with the same body, so a retried payment checkout, email or AI call can't happen twice. A different body under the same key is idempotency_mismatch; a concurrent request with the same key while the first is running is conflict. Streams and audio aren't replayed. Server errors aren't stored, so they can be retried.
Retry 429 (after the reset), 502/503 and network errors with backoff. Never retry 400, 401, 403 or 409 unchanged.
In the MCP server
Tool errors are isError: true results whose text is the same JSON. A failed build waited on by vibiz_deploy comes back as deployment_failed.