Errors

Every error the wondeya API returns is a problem document with the same shape, and every one carries a stable machine-readable code. Client code branches on code. It must never branch on detail, which is human text, localized, and free to change.

The envelope

{
  "type": "https://wondeya.com/docs/errors/wondeya.page.path_taken",
  "title": "Page address already taken",
  "status": 409,
  "detail": "Ya existe otra page con esa dirección en este workspace.",
  "instance": "/workspaces/6620…/pages",
  "code": "wondeya.page.path_taken",
  "requestId": "01JR3…"
}

Field	What it is
`type`	The URI of this problem type. It redirects here (this page has no per-code anchors); treat `code` as the actual identifier to branch on.
`title`	Short, stable, English summary of the type. Never localized, never per-occurrence.
`status`	The HTTP status, repeated in the body.
`detail`	Human explanation of this occurrence, localized. Not a contract.
`instance`	The path where it happened.
`code`	The stable, dot-namespaced identifier. This is the contract.
`requestId`	Matches the `x-request-id` header and the server logs. This is what support asks for.
`errors`	Present on validation failures: one entry per field, each with the field path and a reason.

Public and MCP surfaces send this body as application/problem+json; console routes send the identical body as application/json. Anything that is not an expected error becomes a generic 500 with the code wondeya.internal.error. Stack traces, database messages, prompts and third-party provider errors never appear in a response; they go to the logs, keyed by the same requestId.

Codes by area

Request and transport

Code	Status	Meaning
`wondeya.request.invalid`	400	The request was malformed.
`wondeya.request.validation_failed`	400	Field-level validation failed; see `errors`.
`wondeya.request.payload_too_large`	413	Over the size cap for that route.
`wondeya.request.unprocessable`	422	Well-formed but not acceptable.
`wondeya.rate_limit.exceeded`	429	Too many requests. On `/v1` the budget is per key, shared across all routes.
`wondeya.idempotency.conflict`	422 / 409	An `Idempotency-Key` was reused with a different body (422), or while the first request was still running (409).
`wondeya.service.unavailable`	503	A dependency is down, or the surface is disabled.
`wondeya.internal.error`	500	Unexpected failure. Report the `requestId`.

Authentication and session

Code	Status	Meaning
`wondeya.auth.unauthorized`	401	No valid session.
`wondeya.auth.forbidden`	403	Authenticated, not allowed.
`wondeya.auth.invalid_credentials`	401	Wrong email or password, deliberately the same answer for both.
`wondeya.auth.email_taken`	409	That address already has an account.
`wondeya.auth.weak_password`	422	Password rejected.
`wondeya.auth.email_not_verified`	403	Verify the address first.
`wondeya.auth.token_invalid`	400	A verification, reset or invitation link is invalid or expired.
`wondeya.auth.account_locked`	429	Too many failed attempts.
`wondeya.auth.csrf_failed`	403	A mutation without the `x-csrf-token` header, or with the wrong value.
`wondeya.auth.oauth_failed`	400	One answer for every social sign-in failure, deliberately opaque.
`wondeya.auth.provider_unavailable`	503	The identity provider is unreachable.

Credentials

Code	Status	Meaning
`wondeya.api_key.invalid`	401	Unknown, revoked or expired key: one answer for all three, on purpose.
`wondeya.api_key.scope_missing`	403	The key lacks the scope that call needs.
`wondeya.api_key.limit_reached`	409	Two active keys already exist.
`wondeya.site_key.invalid`	401	The site key does not resolve.
`wondeya.site_key.origin_not_allowed`	403	The calling origin is not registered on that site key.
`wondeya.site_key.origin_invalid`	422	A registered origin could never work as a frame ancestor. The offending value is named in `errors`.
`wondeya.oauth.unauthorized`	401 / 403	MCP surface: no valid OAuth token (401), or a consent or revoke call the session may not make (403).
`wondeya.oauth.insufficient_scope`	403	MCP surface: the connection was granted none of the scopes that tool accepts. Re-connect and grant them.

Workspaces and membership

Code	Status	Meaning
`wondeya.tenant.not_found`	404	No such workspace; also the answer when you are not a member of it.
`wondeya.tenant.slug_taken`	409	That workspace address is taken.
`wondeya.tenant.not_member`	404	Same answer as above, by design.
`wondeya.tenant.insufficient_role`	403	Member where admin or owner is required.
`wondeya.tenant.last_owner`	409	The last owner cannot leave or be removed.
`wondeya.tenant.member_not_found`	404	No such member in this workspace.
`wondeya.tenant.already_member`	409	Already a member.
`wondeya.invitation.invalid`	400	Invitation missing, used or expired.
`wondeya.invitation.email_mismatch`	403	The invitation belongs to another address.
`wondeya.tenant.context_missing` / `wondeya.tenant.scope_violation`	500	Internal isolation guards failing closed. Nothing to fix on your side; report the `requestId`.

Agents

Code	Status	Meaning
`wondeya.agent.not_found`	404	No such agent in this workspace. On the embed resolve and the site-key chat, this is also the one answer for an unknown or revoked site key, a missing agent and a suspended workspace.
`wondeya.agent.invalid`	400	Invalid payload; `errors` names the field.
`wondeya.agent.in_use`	409	A page still answers with this agent; `errors` names the pages. Repoint or delete them first.

Projects (sites) and their addresses

Code	Status	Meaning
`wondeya.project.not_found`	404	No such site in this workspace; also the answer for a site that is not yours.
`wondeya.project.invalid`	400	Invalid payload; `errors` names the field.
`wondeya.project.slug_taken`	409	The address is a global namespace and somebody holds it; `errors` carries an available neighbour. A retired address keeps refusing here until its owner releases it.
`wondeya.project.slug_reserved`	409	The platform owns that name; it is never grantable.
`wondeya.host.taken`	409	The domain is already connected somewhere.
`wondeya.host.invalid`	400	Not a connectable name.
`wondeya.host.site_has_no_home`	409	A domain serves a site at its root; a site with no page at `/` cannot take one yet.
`wondeya.host.edge_unavailable`	503	The CDN could not be reached; nothing was changed. Retry.

Pages and theme

Code	Status	Meaning
`wondeya.page.not_found`	404	No such page in this workspace.
`wondeya.page.invalid`	400	Invalid payload; `errors` names the field.
`wondeya.page.path_taken`	409	Another page of the same site has that path.
`wondeya.page.path_reserved`	409	The platform reserves that path. A different problem from the one above, with a different fix.
`wondeya.page.root_required`	409	The home page (`/`) cannot be unpublished, moved or deleted while other pages of the site are live.
`wondeya.page.og_format_unsupported`	415	A social-card image that is not a PNG, JPEG or WebP with a readable size.
`wondeya.theme.invalid`	400	A token outside the closed set. `errors` names the field.
`wondeya.theme.retired`	410	Per-agent theme overrides were removed; the appearance belongs to the project brand.
`wondeya.host.not_found`	404	Unknown host, unverified domain, unpublished page or suspended workspace: one answer for all of them.

Chat

Code	Status	Meaning
`wondeya.chat.agent_scope_conflict`	400	`agentId` on `POST /chat` belongs to the console’s Preview and is only valid on a session turn. Combined with a site key or a public address it is refused, because the locator already names who answers.

Plans and billing

Code	Status	Meaning
`wondeya.billing.limit_reached`	402	The plan’s ceiling for a counted thing; `errors[0].field` names which (`projects`, `agents`, `pages`, `knowledgeDocuments`, `customDomains`, `seats`). The fix is an upgrade, not a retry.
`wondeya.billing.not_configured`	503	This deployment cannot sell that plan.
`wondeya.billing.no_subscription`	409	No subscription to cancel or change.
`wondeya.billing.provider_unavailable`	502	The payment provider could not be reached.
`wondeya.billing.plan_invalid`	400	The named plan does not exist.
`wondeya.billing.signature_invalid`	400	A payment webhook whose signature failed. Answered to the provider; it never says which check failed.
`wondeya.usage.quota_exhausted`	402	The workspace has spent its AI messages, so the generative turn is refused. Unlike `limit_reached`, this is the chat’s own 402; the fix is an upgrade or a message pack.
`wondeya.usage.budget_exceeded`	429	The workspace’s daily activity ceiling. Unlike the rate-limit 429, it carries no `Retry-After`.

Onboarding

Code	Status	Meaning
`wondeya.onboarding.invalid`	400	Invalid onboarding request: the business name, the description or the audio file failed validation. `errors` names the field.

Knowledge

Code	Status	Meaning
`wondeya.knowledge.source_not_found`	404	No such source in this workspace.
`wondeya.knowledge.source_invalid`	400	Invalid payload, or an upload with no file.
`wondeya.knowledge.format_unsupported`	415	A document format the pipeline cannot read.
`wondeya.knowledge.url_not_allowed`	400	A private address, a forbidden scheme or a forbidden port. Deliberately vague.
`wondeya.knowledge.topic_not_found`	404	No such topic in this scope.
`wondeya.knowledge.topic_invalid`	400	An invalid topic operation, such as merging a topic into itself.

A source that fails after it was accepted does not raise an error: it moves to status: "failed" and carries a machine-readable reason such as unsupported_document, ingest_failed, fetch_timeout, fetch_dns_failed, fetch_response_too_large or fetch_blocked_address:link_local. Branch on those the same way, and show a person the translated version, never the raw code.

Assets

Code	Status	Meaning
`wondeya.asset.not_found`	404	No such asset in this workspace.
`wondeya.asset.invalid`	400	Invalid payload.
`wondeya.asset.format_unsupported`	415	The bytes are not an image or a readable video, whatever the filename says.
`wondeya.asset.id_taken`	409	Another asset in that page already uses the key.
`wondeya.asset.video_too_long`	422	The video is longer than the 60-second ceiling.

Brand

Code	Status	Meaning
`wondeya.brand.not_found`	404	No brand file in that slot.
`wondeya.brand.invalid`	400	Invalid payload; `errors` names the field.
`wondeya.brand.format_unsupported`	415	A format that slot does not accept; `errors` names the file.
`wondeya.brand.svg_rejected`	400	The SVG carried script, handlers or external references; `errors` names each reason.

Generic resources

Code	Status	Meaning
`wondeya.resource.not_found`	404	Fallback for a route or resource that does not exist.
`wondeya.resource.conflict`	409	Fallback conflict.

Two habits worth having

Treat identical 404s as identical. Several codes deliberately collapse distinct situations into one answer: “not a member” reads the same as “no such workspace”, and an unknown host reads the same as an unpublished page. Telling them apart would turn the endpoint into a probe. Do not build UI that guesses which one it really was. Keep the requestId. It is the only handle that ties a failure you saw to the server-side logs of the same request.

Overview

Endpoints

The envelope

Codes by area

Request and transport

Authentication and session

Credentials

Workspaces and membership

Agents

Projects (sites) and their addresses

Pages and theme

Chat

Plans and billing

Onboarding

Knowledge

Assets

Brand

Generic resources

Two habits worth having

​The envelope

​Codes by area

​Request and transport

​Authentication and session

​Credentials

​Workspaces and membership

​Agents

​Projects (sites) and their addresses

​Pages and theme

​Chat

​Plans and billing

​Onboarding

​Knowledge

​Assets

​Brand

​Generic resources

​Two habits worth having

The envelope

Codes by area

Request and transport

Authentication and session

Credentials

Workspaces and membership

Agents

Projects (sites) and their addresses

Pages and theme

Chat

Plans and billing

Onboarding

Knowledge

Assets

Brand

Generic resources

Two habits worth having