thelastapi
Console
Reference

Errors

Every error code, its HTTP status, what it means and what to do next.

Open as .md

Errors are always JSON, with the same shape everywhere:

JSON
{ "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." } } }
  • code is stable: branch on it, never on message.
  • message says 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.reason refines 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 type and param so OpenAI SDKs read them.

Codes

CodeStatusMeaningNext step
invalid_request400The request is malformed or a field is wrong. details names the field (issues[].path, param, problems)Fix the field; don't retry unchanged
content_filtered400An AI content filter refused the requestChange the input
context_length_exceeded400The AI input is longer than the model's windowShorten it or use a larger model
unauthorized401Missing, unknown or revoked key; an app key on an account routeCheck the key and its kind
forbidden403Not allowed for this key. With reason: owner_only: the key is Limited without details.permissionGive the person details.grant_url (allows that permission for this key, or everything) or details.console_url (do it themselves); retry once allowed
no_account403Signed in to the console with no account yetCreate an account or link a key in the console
not_found404No such object on this account or in this environmentCheck the id and env
conflict409The object's state doesn't allow it (details.reason says why), or a concurrent request with the same Idempotency-Key is still runningRead the object again; act on reason
domain_taken409The slug or domain belongs to someone elsePick another
dependency_not_ready409A resource this needs is missing or still provisioningAdd it or wait, then retry
insufficient_balance409The project's balance can't cover a refundWait for more sales, or refund less
payment_required402The 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_exceeded413A stored quota is full (replay)Delete or wait for retention
payload_too_large413The body or upload is over its capSend less
idempotency_mismatch422The same Idempotency-Key was used with a different bodyUse a new key for a new request
rate_limited429A limit was reached; details says which and resets_atWait (Retry-After or resets_at); don't loop
client_outdated426The thelastapi CLI that called is older than the API supports; details.minimumUpdate it: npm install -g @vibiz/cli@latest, then retry
internal500Our bugRetry once; then contact support with X-Request-Id
provider_failed502The 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 oneAct on the reason; retrying unchanged rarely helps
provider_unavailable503The service is unavailable right now, or the call timed out (details.reason)Retry later with backoff
model_unavailable503No route can run the model you asked for right now. thelastapi never swaps in another modelRetry after details.retry_after_seconds, or pick another model
not_configured503This deployment doesn't offer that capability nowUse 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:

JSON
{ "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." }] } } }
  • field is the first field (a dotted path into the body, or the query parameter), fields all 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.