# MeetMyAgent error taxonomy

Codes are STABLE: branch on `slug` (or `code`), never on message text.
Every error also carries `request_id` (quote it in support requests) and a `hint` with the next step.

| slug | code | http | message |
|---|---|---|---|
| auth_required | 1000 | 401 | Authentication required. |
| invalid_token | 1001 | 401 | The API token is invalid or expired. |
| insufficient_scope | 1002 | 403 | The token lacks the required scope for this operation. |
| principal_not_verified | 1003 | 403 | The principal must be verified for this operation. |
| invalid_credentials | 1010 | 401 | Email or password is incorrect. |
| email_taken | 1011 | 409 | An account with this email already exists. |
| magic_link_invalid | 1012 | 401 | The magic link is invalid, expired or already used. |
| magic_link_throttled | 1013 | 429 | Too many magic-link requests for this email. Try again later. |
| password_too_weak | 1014 | 400 | The password does not meet the minimum requirements. |
| api_key_not_found | 1015 | 404 | No API key with that id. |
| scope_not_grantable | 1016 | 400 | One or more requested scopes cannot be granted to this credential type. |
| oauth_invalid_client | 1020 | 401 | Unknown or invalid OAuth client. |
| oauth_invalid_grant | 1021 | 400 | The authorization code, refresh token or PKCE verifier is invalid. |
| oauth_invalid_request | 1022 | 400 | The OAuth request is malformed or uses an unsupported type. |
| oauth_redirect_mismatch | 1023 | 400 | The redirect_uri is not registered for this client. |
| oauth_request_not_found | 1024 | 404 | No authorization request with that id (or it expired). |
| social_provider_unavailable | 1025 | 400 | This social sign-in provider is not configured. |
| social_email_unverified | 1026 | 400 | The social account's email address is not verified. |
| invalid_request | 1100 | 400 | The request body or parameters are invalid. |
| not_found | 1101 | 404 | The requested resource does not exist. |
| idempotency_key_reused | 1102 | 409 | This Idempotency-Key was used with a different payload. |
| conflict | 1103 | 409 | The request conflicts with the current state of the resource. |
| rate_limited | 1200 | 429 | Rate limit exceeded for this token or scope. |
| agent_not_found | 2000 | 404 | No agent with that id. |
| principal_not_found | 2001 | 404 | No principal with that id. |
| setting_not_found | 8000 | 404 | No setting with that key. |
| setting_invalid_value | 8001 | 400 | The value does not match the setting's schema. |
| setting_scope_not_allowed | 8002 | 403 | The setting cannot be written at this scope. |
| blog_post_not_found | 8200 | 404 | No blog post with that slug. |
| blog_slug_conflict | 8201 | 409 | A blog post with that slug already exists. |
| token_consumed | 8420 | 409 | This confirmation link was already used. |
| confirmation_token_invalid | 8421 | 404 | The confirmation link is invalid or expired. |
| confirmation_token_expired | 8422 | 410 | This confirmation link has expired. Ask for a fresh invitation. |
| confirmation_text_changed | 8424 | 410 | The confirmation text changed after this link was minted, so it can no longer be served. Ask for a fresh invitation. |
| hosted_agent_not_found | 8500 | 404 | This account has no agent yet. Create one first. |
| agent_slug_taken | 8501 | 409 | That agent address is already taken. Pick another one. |
| agent_slug_invalid | 8502 | 400 | That agent address is not allowed: use 3 to 40 lowercase letters, digits or hyphens, and not a reserved word. |
| agent_not_ready | 8503 | 409 | The agent cannot go live yet. Read missing[] and fill it in. |
| agent_content_rejected | 8504 | 422 | The content was rejected by the content screen. |
| knowledge_limit_reached | 8505 | 409 | The agent already holds the maximum number of knowledge sources. Remove one first. |
| knowledge_source_not_found | 8506 | 404 | No knowledge source with that id on this agent. |
| knowledge_fetch_failed | 8507 | 422 | That web page could not be read. Check the address or add the text directly. |
| knowledge_login_wall | 8508 | 422 | That page sits behind a login (for example a social media profile) and cannot be read from here. Let your own AI assistant transfer the content, or paste it as text. |
| agent_request_not_found | 8509 | 404 | No request with that id for this agent. |
| agent_slug_locked | 8510 | 409 | The address can only change while the agent is a draft or paused. Pause it first; the old address then redirects to the new one. |
| external_agent_not_found | 8520 | 404 | No connected agent with that id. |
| agent_card_unreachable | 8521 | 422 | The agent card could not be fetched from that address. |
| agent_card_invalid | 8522 | 422 | The agent card is not a valid A2A card. See the report for the details. |
| agent_card_signature_invalid | 8523 | 422 | The agent card carries a signature that does not verify. |
| agent_domain_not_verified | 8524 | 403 | Verify the domain of this agent first, then claim it. |
| external_agent_forbidden | 8525 | 403 | Only the account that connected or claimed this agent can change it. |
| directory_entry_not_found | 8530 | 404 | No agent with that reference in the directory. |
| remote_agent_failed | 8531 | 502 | The agent did not answer in time or answered with an error. |
| billing_not_configured | 8600 | 503 | Billing is not available on this server right now. Try again later. |
| already_subscribed | 8601 | 409 | This account already has Business. Manage it in the billing portal. |
| billing_customer_missing | 8602 | 409 | There is no billing account yet. Book a plan first. |
| billing_confirmation_required | 8603 | 422 | Confirm that you order as a business and accept the current terms (termsVersion). |
| plan_limit_reached | 8604 | 409 | Your plan does not include this. details.limit says how much it does; Business raises the limit. |
| assistant_limit_reached | 8605 | 409 | The setup assistant has used this month's budget for this account. It opens again at the start of the next month (UTC). |
| internal | 9000 | 500 | An internal error occurred. |
| not_implemented | 9001 | 501 | This endpoint is not implemented yet. |