Error codes

When Maitento refuses a request, it says why with a stable code such as api:billing:out-of-credit. This page lists every one, in 24 areas: 227 codes, and 4 more that are built from a value, such as api:<kind>:delete:in-use. It is generated from Maitento’s code, so it lists what the API sends.

Branch on the HTTP status and the code, never on the message: messages are English for developers and logs, and their wording can change.

How errors arrive

Status	Body	Means
400	{"validationFailures": [{"errorCode", "memberName", "message"}]}	the request was refused and nothing happened; there is one failure for each reason
403	{"code", "error"}, or empty	you’re signed in but not allowed
413	{"code": "api:request-too-large", "error", "maxRequestBodyBytes"}	the body is too large
429	{"code": "api:rate-limited", "error", "retryAfterSeconds"}	slow down; the wait is also sent as Retry-After

In a 400, errorCode is the code, memberName the request field it is about (request when it’s about the whole request), and message says what is wrong:

{
  "validationFailures": [
    { "errorCode": "api:credentials:name-in-use", "memberName": "name", "message": "The tenant already has a credential by that name." }
  ]
}

A few codes don’t arrive as an error: a credential test’s result, an embedding test’s result, a run’s failure details and the provider sign-in’s redirect carry them. Their sections say where. 401 and 404 have no code: see Errors in the API overview.

In the SDKs

Every SDK raises a typed error for a refused request:

Status	TypeScript	Python	C#
400	ValidationError: codes, and failures, each with code, member and message	ValidationError: codes, and failures, each with code, member and message	MaitentoValidationException: ValidationResults, each with ErrorCode, MemberName and Message
403	PermissionError: code	PermissionError: code	MaitentoApiAuthenticationException: StatusCode, and the body in ResponseBody
413	RequestTooLargeError: code, maxRequestBodyBytes	RequestTooLargeError: code, max_request_body_bytes	MaitentoApiException: StatusCode, and the body in ResponseBody
429	RateLimitError: code, retryAfter	RateLimitError: code, retry_after	MaitentoApiException: StatusCode, and the body in ResponseBody

In TypeScript and Python every API error is an ApiError, with the status and the code (a 400’s first failure’s), and every SDK error is a MaitentoError. In C# every SDK error is a MaitentoSdkException.

Codes about one field

A request body that fails a check on a field answers api:validation-failure:<field>, described below. Some checks answer the plain api:validation-failure with the field in memberName, and some answer with the field’s path itself as the code, without api: (name, request:mount-name). Treat a code that doesn’t start with api: as “this field is wrong”, and read memberName and the message.

Codes by area

The Status column gives the HTTP status, and the request field (memberName) where a code always names the same one. Codes that only Maitento’s own operators, or its own services, can receive aren’t listed.

• Any request: 6 codes
• Plans and billing: 23 codes
• Starting runs: 16 codes
• Talking to a run: 4 codes
• Why a run failed: 4 codes
• Listing and keeping runs: 11 codes
• Credentials: 23 codes
• Credential tests: 9 codes
• Credential stacks: 10 codes
• Model keys: 11 codes
• Knowledge bases: 22 codes
• Embedding tests: 9 codes
• Files: 1 code
• Definitions and namespaces: 7 codes
• Tools and connectors: 2 codes
• Automations: 2 codes
• Webhooks: 4 codes
• Build history: 3 codes
• Usage: 7 codes
• Users, API keys and invitations: 15 codes
• Signing up and signing in: 14 codes
• Signing in with a provider: 25 codes
• Notifications: 1 code
• Cloud shell: 2 codes

Any request

Codes any call can answer with.

Code	Status	What it means	What to do
api:forbidden	403	You’re signed in, but not allowed to do this, and no more specific reason applies.
api:rate-limited	429	Too many requests in a short time.	Wait retryAfterSeconds (also sent as Retry-After), then try again. The SDKs wait and retry for you where that is safe.
api:request-too-large	413	The request body is over this call’s limit, which the answer’s maxRequestBodyBytes gives.	Send a smaller body.
api:validation-failure	400	The request failed a check. memberName names the field (request when the body is missing), and the message says what is wrong.	Check what you entered and try again.
api:validation-failure:<field>	400	The request body failed a check on a field. <field> is the field’s path in kebab case, with : between levels: api:validation-failure:system-prompt, api:validation-failure:credentials[0]:value. memberName is the same field, and the message says what is wrong.
api:validation-failure:interaction	400	The interaction definition failed validation. There is one failure for each problem, and its message says what to fix.

Plans and billing

What your plan lets you start and keep, and buying or changing a plan. A start your plan refuses creates nothing. Limits explains the refusals, and Plans and billing the plans.

Code	Status	What it means	What to do
api:billing:alert-threshold-invalid	400 · billing	A low-balance alert percentage outside 1 to 100.	Choose a share of the last top-up from 1 to 100 percent, or turn the email off.
api:billing:allowance-used	400 · billing	The plan’s allowance for this kind of work is used up for the period, and the plan can’t top up.	Upgrade to carry on now.
api:billing:already-subscribed	400 · billing	Your tenant already has a paid plan.	Change that plan instead of buying another.
api:billing:auto-top-up-threshold-invalid	400 · billing	An auto top-up threshold that’s negative, past the largest top-up, or not in whole cents.	Choose a balance from 0 to the largest top-up, in whole cents, to start an automatic top-up.
api:billing:change-awaiting-payment	400 · billing	A change while an earlier one still waits for its invoice to be paid.	Pay it, or wait for it to lapse, then try again.
api:billing:invalid-return-path	400 · billing	The returnPath isn’t a plain path in the portal, such as /billing, for the payment page to send you back to.
api:billing:lanes-over-limit	400 · billing	That’s more extra lanes than this plan can hold.	Choose fewer.
api:billing:mixed-change	400 · billing	A change that adds something and takes something away at once; made as two changes.	Make the addition now, and the reduction (which waits for your renewal) as a separate change.
api:billing:no-billing-account	400 · billing	There’s no billing account yet, because nothing has been bought.	Buy a plan or a top-up first.
api:billing:no-change	400 · billing	The plan asked for is the plan the tenant already has.
api:billing:no-subscription	400 · billing	A plan change, cancellation or withdrawal on a tenant with no paid subscription.	Choose a plan to buy one.
api:billing:nothing-scheduled	400 · billing	Nothing is booked for the renewal, so there’s nothing to withdraw.
api:billing:out-of-credit	400 · billing	The tenant is out of credit: top up or upgrade.	Top up or upgrade, then try again.
api:billing:payments-not-configured	400 · billing	Payments aren’t available on this Maitento, so nothing can be bought here.
api:billing:premium-not-included	400 · billing	The plan doesn’t include capsules and code pipelines.	Upgrade to run them.
api:billing:storage-cap-reached	400 · billing	The write would take the tenant over its storage cap, and its plan can’t pay for storage above it.	Delete what you no longer need, or upgrade.
api:billing:subscription-frozen	400 · billing	A plan change while frozen after a failed renewal: the failed invoice is paid first.	Pay it from the payment provider’s page before changing the plan.
api:billing:tenant-locked	400 · billing	A platform admin has locked the tenant: nothing new starts until it’s unlocked.	Contact support to have it unlocked.
api:billing:tier-not-available	400 · billing	That plan can’t be bought.	Choose another.
api:billing:top-up-amount-invalid	400 · billing	The top-up amount is less than the smallest top-up, more than the largest, or not in whole cents.	Choose an amount between the smallest and the largest top-up, in whole cents.
api:billing:top-up-not-available	400 · billing	Your plan can’t buy credit.	Upgrade to a paid plan to top up.
api:file-system:limit-reached	400 · fileSystems	The plan holds no more file systems.	Delete one you no longer use, or upgrade.
api:partition:limit-reached	400 · partitions	The plan holds no more knowledge bases.	Delete one you no longer use, or upgrade.

Starting runs

Starting an interaction or an app. A start that is refused creates nothing. Child runs are refused the same way, and the refusal is what their start returns.

Code	Status	What it means	What to do
api:apps:input-missing	400 · inputs	An app run was started without a value for an input the app declares.
api:interactions:ai-model-override-invalid	400 · aiModelOverrides	An AI model override is malformed, names an unknown model, or one that cannot run an interaction.
api:interactions:input-empty	400 · inputs	A required input was given empty, and it has no default.
api:interactions:input-invalid	400 · inputs	An input’s value is not of its type (a number, a date, a secret’s id…).
api:interactions:input-required	400 · inputs	A required input was not given (member inputs; the message names it).
api:interactions:input-unknown	400 · inputs	An input the interaction does not declare was given.
api:interactions:loom-gift-invalid	400 · loomGifts	Threads handed to an agent at start are refused (too many, unknown, or private to their loom).
api:interactions:loom-mapping-invalid	400 · loomMappings	A loom mapping is malformed: an unknown agent, no id or name, or a namespace given twice.
api:interactions:loom-not-enabled	400	Memory (looms) was mapped or handed over for an interaction that has none.
api:interactions:loom-not-found	400 · loomMappings	A loom, or the namespace named to find it in, does not exist.
api:interactions:no-enabled-version	400 · interactionId	Every version of the interaction is disabled.
api:interactions:not-found	400 · interactionId	The interaction does not exist in the tenant.
api:interactions:response-schema-invalid	400 · responseJsonSchema	The responseJsonSchema given with the start is not a valid JSON schema.
api:interactions:swarm-limits-invalid	400 · swarmLimits	The start’s sub-interaction limits are out of range.
api:web:download-partition-invalid	400	The knowledge base named for the run’s web downloads can’t be used: it isn’t one of your tenant’s temporary knowledge bases.	Name one of your tenant’s temporary knowledge bases.
api:web:download-partition-required	400	The run’s agents may fetch from the web, and nothing names a knowledge base to keep what they fetch: not the start, the namespace or the tenant.	Name a temporary knowledge base for the run’s downloads, or set a default one for the namespace or the tenant.

Talking to a run

Sending a message or a vote to an interaction run.

Code	Status	What it means	What to do
api:interaction-process:complete	400 · Request	The run has ended (Finished, Error, Killed); nothing was stored. Permanent.
api:interaction-process:no-vote-pending	400 · Request	A vote was sent while no vote or solution proposal is open.
api:interaction-process:not-awaiting-input	400 · Request	A vote needs the run parked at a human-input gate, and it is not (it is running). Retry later.	Try again when it asks.
api:interaction-process:vote-pending	400 · Request	The run is parked on a vote or solution proposal: it takes a vote, not a message.	Vote instead of sending a message.

Why a run failed

A run that can’t make a model call ends with status Error, and its failure details end with one of these codes in brackets: ... [api:credentials:all-failed]. See when the stack can’t serve a call and when there’s no key.

Code	Status	What it means	What to do
api:credentials:all-failed	In the run	Every credential that could serve the call failed.	Replace the key, then retry. Test the credential to see which key fails.
api:credentials:no-usable-credential	In the run	No credential in the run’s stack serves this model, or every one that does is switched off.	Add a credential that serves the model to the stack, or change the entries’ rules.
api:model-keys:all-failed	In the run	Every key a model call could use for the provider failed (authentication, quota or endpoint), and the platform’s key is not allowed. Carried at the end of a run’s failure text, in brackets.	Check the key with the provider, and replace it.
api:model-keys:none-for-provider	In the run	A model call had no key to run on: none supplied with the run, none of the tenant’s for the provider, and the platform’s key not allowed. Carried at the end of a run’s failure text, in brackets.	Add a model key for the provider, or give the run a credential stack.

Listing and keeping runs

Listing runs, and how long they are kept.

Code	Status	What it means	What to do
api:processes:invalid-cursor	400 · cursor	The cursor isn’t one this list gave out.	Start again from the first page.
api:processes:invalid-ids	400 · ids	An id isn’t a run id, or more than 50 are asked for at once.
api:processes:invalid-namespaces	400 · namespace	More than 50 namespaces are asked for at once.
api:processes:invalid-state	400 · state	The state isn’t active, waiting or terminal.
api:processes:invalid-status	400 · statuses	A status isn’t one that the run types asked for can have.
api:processes:invalid-type	400 · types	A type isn’t App, Interaction, Capsule or CodePipeline.
api:processes:retention:lease-inherited	400 · processId	The run’s lease is inherited from a retained ancestor — release that run instead.	Release that run instead.
api:processes:retention:lease-limit-reached	400 · processId	The tenant already holds its maximum of own leases.	Release runs you no longer need, then try again.
api:processes:retention:note-too-long	400 · note	The note is too long.	Keep it to 500 characters.
api:processes:summary:invalid-hours	400 · hours	hours isn’t from 1 to 168.
api:tenant:retention-out-of-range	400 · hours	The retention asked for is outside what your plan allows.	Choose a retention your plan allows, in whole hours. Upgrade to keep runs longer.

Credentials

Adding and changing credentials, and subscription sign-ins for code pipelines.

Code	Status	What it means	What to do
api:credentials:cloud-invalid	400	Check the cloud settings: Bedrock and Vertex are for Anthropic credentials, with a region (and for Vertex a project) and no endpoint.
api:credentials:endpoint-invalid	400 · endpoint	An endpoint is a whole https:// address, with no user name, password, query or fragment.
api:credentials:endpoint-not-public	400 · endpoint	That endpoint isn’t on the public internet. Maitento only calls public https endpoints.
api:credentials:key-invalid	400 · keys	A key is one piece of text with no spaces, at most 4096 characters (a Vertex key is the whole JSON key file).
api:credentials:key-unknown	400 · keys	A key on this credential changed while you were editing it. Close this and open it again.
api:credentials:keys-required	400 · keys	Add at least one key.
api:credentials:limit-reached	400 · credentials	Your plan holds no more credentials.	Delete one you no longer use, or change plan.
api:credentials:models-invalid	400 · models	Check the models: each needs a name with no spaces, listed once, with a positive context window if you give one.
api:credentials:name-in-use	400 · name	You already have a credential with that name.	Choose another.
api:credentials:name-required	400	Give the credential a name.
api:credentials:name-too-long	400 · name	A credential’s name is at most 100 characters, with no line breaks.
api:credentials:not-a-sign-in	400	That credential isn’t a sign-in for this coding agent.
api:credentials:provider-invalid	400 · provider	Choose a provider.
api:credentials:sign-in-code-required	400 · code	Paste the code the provider showed after you signed in.
api:credentials:sign-in-fixed	400 · credential	A sign-in’s provider, endpoint and tokens come from signing in.	Sign in again to change them.
api:credentials:sign-in-refreshed-by-caller	400 · credentialId	The application that brought this sign-in keeps it fresh, so it can’t be signed in again here.
api:credentials:sign-in-refreshed-here	400 · id	Maitento keeps this sign-in fresh itself.	Sign in again to replace its tokens.
api:credentials:sign-in-refused	400 · code	The provider refused that code. Copy it again, whole, from the page it showed you, or start again.
api:credentials:sign-in-tokens-invalid	400	The sign-in’s tokens are incomplete.	Send the access and refresh tokens, Codex’s ID token, and when the access token expires.
api:credentials:sign-in-unavailable	400	The provider’s sign-in isn’t answering right now.	Try again in a few minutes.
api:credentials:sign-in-unknown	400 · signInId	That sign-in has finished or expired.	Start again.
api:credentials:tag-invalid	400 · tag	A tag is at most 100 characters, with no line breaks.
api:credentials:too-many-keys	400 · keys	A credential holds at most 10 keys.

Credential tests

A test of a credential answers 200 whether it passes or not. Each key that fails has one of these codes as its errorCode, and the result’s own errorCode is the first failing key’s.

Code	Status	What it means	What to do
api:credentials:test-auth-failed	In the result	The provider refused the key.
api:credentials:test-endpoint-not-found	In the result	Nothing answers at the endpoint’s models route.	Check the endpoint.
api:credentials:test-endpoint-refused	In the result	Maitento won’t connect to that endpoint’s address.
api:credentials:test-not-supported	In the result	Claude on Bedrock or Vertex can’t be tested here.
api:credentials:test-provider-error	In the result	The provider had an error of its own.	Try again later.
api:credentials:test-quota-exhausted	In the result	The key’s account is out of quota or can’t pay.
api:credentials:test-rejected	In the result	The provider turned the request down.
api:credentials:test-timed-out	In the result	The endpoint didn’t answer in time.
api:credentials:test-unreachable	In the result	The endpoint couldn’t be reached.

Credential stacks

Making and using credential stacks.

Code	Status	What it means	What to do
api:credential-stacks:credential-unknown	400 · entries	A credential in this stack no longer exists.	Remove it, then save.
api:credential-stacks:entries-invalid	400 · entries	Check the entries: a stack has 1 to 20 credentials, and each rule names at least one model or endpoint kind.
api:credential-stacks:in-use-as-default	400 · id	This stack is a default, for the tenant or a namespace, so it can’t be deleted.	Change that default first.
api:credential-stacks:in-use-by-partition	400 · id	A knowledge base embeds with this stack, so it can’t be deleted.	Give the knowledge base another stack, or clear its stack, first.
api:credential-stacks:limit-reached	400 · credentialStacks	Your plan holds no more credential stacks.	Delete one you no longer use, or change plan.
api:credential-stacks:name-in-use	400 · name	You already have a stack with that name.	Choose another.
api:credential-stacks:name-required	400	Give the stack a name.
api:credential-stacks:name-too-long	400 · name	A stack’s name is at most 100 characters, with no line breaks.
api:credential-stacks:unknown	400	That stack doesn’t exist in this tenant.
api:credential-stacks:with-credentials	400	A run can’t have a stack and keys of its own at once.	Choose one.

Model keys

Adding and changing your tenant’s model keys.

Code	Status	What it means	What to do
api:model-keys:api-key-invalid	400 · apiKey	The key is too long, or holds whitespace or control characters.	Paste the key on its own: no spaces or line breaks, and at most 4,096 characters.
api:model-keys:api-key-required	400 · apiKey	No key was given on create (or an empty one on update).	Paste the API key.
api:model-keys:base-url-invalid	400 · baseUrl	Not an absolute https URL with a host and no embedded credentials.	Enter a full https URL, without a user name or password.
api:model-keys:base-url-not-allowed	400 · baseUrl	The host is not a public endpoint (loopback, private, link-local or an internal name).	Use a public endpoint.
api:model-keys:label-required	400 · label	No label was given.	Give the key a label.
api:model-keys:label-too-long	400 · label	The label is longer than 100 characters.	Use at most 100 characters for the label.
api:model-keys:limit-reached	400 · provider	The tenant already holds the most keys it may.	Delete keys you no longer use, then try again.
api:model-keys:model-name-overrides-invalid	400 · modelNameOverrides	A blank or over-long name, or too many entries.	Check the model name overrides: each needs both names, up to 200 characters each, and a key can have at most 50.
api:model-keys:priority-out-of-range	400 · priority	Outside 0–1000.	Choose a priority from 0 to 1000.
api:model-keys:provider-invalid	400 · provider	The provider is not one a key can be stored for.	Choose a provider a model key can be for.
api:model-keys:provider-required	400 · provider	No provider was given.	Choose a provider.

Knowledge bases

Knowledge bases (partitions in the API) and the embedding models that index them. A file that couldn’t be indexed has api:embeddings:fallback-not-permitted or api:embeddings:credentials-exhausted in its indexingFailure. See Knowledge.

Code	Status	What it means	What to do
api:embeddings:credential-api-key-required	400 · credentials	An embedding credential without an API key.
api:embeddings:credential-base-url-invalid	400 · baseUrl	A credential’s base URL is not an absolute https URL.
api:embeddings:credential-base-url-not-allowed	400 · baseUrl	An embedding credential’s base URL is not a public provider endpoint.
api:embeddings:credential-base-url-required	400	A credential for a provider with no default endpoint (Qwen) carries no base URL.
api:embeddings:credential-id-duplicate	400 · credentials	Two embedding credentials share a credential id.
api:embeddings:credential-id-required	400 · credentials	An embedding credential without a credential id.
api:embeddings:credential-provider-mismatch	400	A credential is for a different provider from the partition’s profile.
api:embeddings:credentials-empty-without-consent	400 · credentials	An empty embedding credential stack without consent to Maitento’s key.
api:embeddings:credentials-exhausted	400 · partition	Every key that could embed for the knowledge base failed, or is switched off for failing, and Maitento’s own key may not be used.	Check the keys.
api:embeddings:fallback-not-permitted	400 · partition	Nothing can embed for the knowledge base: it has no embedding credentials or stack of its own, your tenant has no model key for the provider, and Maitento’s own key may not be used for it.	Add a model key for the provider, or give the knowledge base credentials or a stack.
api:embeddings:index-rebuild-failed	400 · partition	Search is refused: rebuilding the knowledge base’s index for its new embedding model stopped, because its keys failed.	Fix the keys, and the rebuild carries on.
api:embeddings:index-rebuilding	400 · partition	Search is refused while the knowledge base’s index is rebuilt for a new embedding model, because a half-built index would answer from only some of the files. The message says how far it has got.	Try again when it is done.
api:embeddings:invalid-profile	400 · profile	The embedding profile isn’t valid. The message says why.
api:embeddings:profile-changed	400	The knowledge base’s embedding model changed while its credentials or stack were being set.	Set them again.
api:embeddings:reindex-in-progress	400 · profile	The knowledge base’s index is already being rebuilt.	Wait for it to finish before changing the embedding model again.
api:embeddings:reindex-not-permitted	400 · profile	The profile asked for needs the index rebuilt, and the request set allowReindex to false. Nothing was changed.
api:partition:files:invalid-cursor	400 · cursor	The cursor isn’t one this list gave out.	Start again from the first page.
api:partition:lifetime-not-temporary	400 · fileLifetimeHours	Only a temporary partition has a file lifetime.
api:partition:lifetime-out-of-range	400 · fileLifetimeHours	A temporary partition’s file lifetime is outside 1–720 hours.
api:partition:not-empty	400 · id	A knowledge base still holds files, so it cannot be deleted. Delete them first.
api:partition:temporary-not-indexed	400 · id	A temporary partition is never indexed, so it has no embedding model to change.
api:partition:too-many-ids	400 · ids	More partition ids than one status request may name.

Embedding tests

A test call of an embedding model (POST /partitions/embedding-profile/probe) says what went wrong in its result’s errorCode. A change to a custom embedding model makes the same call first, and is refused with 400 and the same code when it fails.

Code	Status	What it means	What to do
api:embeddings:probe-credential-rejected	In the result, or 400	Every key was refused (401/403, or Gemini’s 400 for an invalid key).
api:embeddings:probe-dimension-mismatch	In the result, or 400	The model answered, but its embeddings have a different number of dimensions from the profile’s. The result says how many it measured.
api:embeddings:probe-endpoint-unreachable	In the result, or 400	The base URL’s host does not exist, or refused a secure connection.
api:embeddings:probe-failed	In the result, or 400	Anything else: a refused request, a provider outage, a response that was not an embedding.
api:embeddings:probe-model-not-found	In the result, or 400	The endpoint answered 404: the model id (or the base URL’s path) is wrong.
api:embeddings:probe-needs-credentials	400	A test call, or a custom embedding model, needs at least one key of your own. It never uses Maitento’s.
api:embeddings:probe-quota-exceeded	In the result, or 400	The account behind the key cannot pay for the call, or is over a quota.
api:embeddings:probe-rate-limited	In the result, or 400	The provider is rate-limiting the key; try again shortly.
api:embeddings:probe-timed-out	In the result, or 400	The call did not finish in time.

Files

Files in a knowledge base.

Code	Status	What it means	What to do
api:files:update-conflict	400 · file	Something else changed the file while it was being updated. Nothing was changed.	Try again.

Definitions and namespaces

Deploying, changing and deleting definitions and namespaces. A delete that is blocked answers 400 with one failure for each reason, and each failure’s message names what blocks it.

Code	Status	What it means	What to do
api:<kind>:delete:has-active-runs	400 · id	It has runs that are still going, so it can’t be deleted. The message lists them. <kind> is agent, app, capsule, code-pipeline or interaction.	Wait for them to end, or kill them.
api:<kind>:delete:in-use	400 · id	The latest version of another definition uses this one, so it can’t be deleted. The message lists them. <kind> is agent, connector, interaction or tool.	Remove it from those definitions, or delete them first.
api:<kind>:delete:referenced-by-automation	400 · id	An automation starts it, so it can’t be deleted. The message names the automations. <kind> is app, capsule, code-pipeline or interaction.	Remove it from the automation first.
api:definitions:version-conflict	400 · versions	Another change, such as a second deploy of the same namespace, kept adding versions to the definition while this one was being added. Nothing was changed.	Try again.
api:namespace:delete:in-progress	400 · id	A delete of a namespace another delete is checking right now.	Wait for that delete to finish.
api:namespace:delete:not-empty	400 · id	The namespace still holds definitions, automations, memory or file systems. The message lists them.	Delete them first.
api:namespace:deleting	400 · namespaceId	This namespace is being deleted, so nothing can be created in it.	Choose another namespace.

Tools and connectors

Tools, and the connectors they call. See Tools.

Code	Status	What it means	What to do
api:connectors:address-blocked	400 · url	The connector’s address is not one Maitento will call: a loopback, private, link-local or cluster address, a name that resolves to one, an internal name such as localhost, or one of the platform’s own hosts. Refused when the connector is deployed if the URL names such an address outright, and when a tool is called (including on every redirect) if its name resolves to one.	Use a public address.
api:connectors:secret-missing	400 · externalOperations	The tool’s connector needs a secret in a header (auth = "Header"), and nothing gives it one: not the tool’s own auth, not the interaction’s binding, and no run input. Refused when an interaction that can never supply it is deployed; when the secret is an optional run input that a run was not given, calling the tool answers with this code.	Set the tool’s auth, its binding’s auth, or accept the secret as a run input.

Automations

Creating and triggering automations.

Code	Status	What it means	What to do
api:automations:app-input-missing	400 · actions	On create and update: an action starts an app version without a value for one of the inputs it declares (its main’s parameters). Every app input is required.
api:automations:start-failed	400 · actions	From a manual trigger: none of the automation’s actions could be started. The message says why; the failures that follow it carry the cause’s own codes. Each failure is in the history too.

Webhooks

Registering webhooks, and delivering to them.

Code	Status	What it means	What to do
api:webhook:header-value-required	400 · headers	A header has no value, and there is no stored value to keep.	Send its value.
api:webhook:secret-required	400 · secret	An update that moves the registration to a new origin without supplying the secret again.
api:webhooks:address-blocked	400 · url	The webhook’s address is not one Maitento will deliver to: a loopback, private, link-local or cluster address, a name that resolves to one, an internal name such as localhost, or one of the platform’s own hosts. Refused when the webhook is registered if the URL names such an address outright; otherwise each delivery to it is recorded as failed with this code in its failure details.	Use a public address.
api:webhooks:already-exists	400 · url	A live registration already has this URL and type.

Build history

Listing a namespace’s builds.

Code	Status	What it means	What to do
api:builds:invalid-cursor	400 · cursor	The cursor isn’t one this list gave out.	Start again from the first page.
api:builds:invalid-namespace	400 · namespace	No namespace was named.
api:builds:invalid-outcome	400 · outcome	The outcome filter isn’t Succeeded, Failed or Rejected.

Usage

Reading your usage.

Code	Status	What it means	What to do
api:usage:invalid-bucket	400 · bucket	Hourly totals cover at most 31 days.	Choose daily or weekly totals for a longer range.
api:usage:invalid-dimension	400 · groupBy	Usage can’t be grouped that way.
api:usage:invalid-filter	400	One of the filters isn’t valid.	Remove it and try again.
api:usage:invalid-metric	400 · metric	That measure isn’t available.
api:usage:invalid-namespaces	400 · namespace	More than 50 namespaces are asked for at once.	Filter by at most 50 namespaces at a time.
api:usage:invalid-range	400	That date range can’t be shown.	Choose a start before the end, at most 400 days apart.
api:usage:invalid-sort	400 · sort	Usage can’t be sorted that way.

Users, API keys and invitations

The people in your tenant, their API keys, and inviting more.

Code	Status	What it means	What to do
api:invitation:code-no-remaining-uses	400 · invitationCodeId	You’ve used every invitation on your code.	Cancel a pending invite to free one up.
api:invitation:email-address-already-in-use	400 · emailAddress	Someone already has an account with this email address.
api:invitation:email-address-already-invited	400 · emailAddress	You’ve already invited this email address, and that invite hasn’t been used yet.
api:invitation:grants-admin-requires-admin	403	Only a tenant admin can invite another admin.
api:invitation:grants-admin-requires-invite-to-tenant	400 · grantsAdmin	An admin invite has to invite the person into this tenant.
api:invitation:invalid-scope	400 · scope	That list of invites isn’t available.
api:invitation:invite-to-tenant-requires-admin	403	Only a tenant admin can invite people into this tenant.
api:invitation:no-matching-codes	400 · invitationCodeId	That invitation code doesn’t exist or isn’t yours.
api:invitation:tenant-scope-requires-admin	403	Only a tenant admin can see everyone’s invites.
api:invitation:too-many-pending-invites	400 · emailAddress	This tenant already has 100 invites waiting to be accepted.	Cancel the ones you no longer need, then try again.
api:invitation:used-or-cancelled	400 · invitationId	This invite has already been used or cancelled.
api:user:api-key-create:expiry-in-past	400 · dateExpires	The API key’s expiry date is in the past.	Choose an expiry date in the future.
api:user:api-key-create:name-exists	400 · name	You already have an API key with this name.
api:user:cannot-modify-own-account	400 · userId	You can’t change your own role or status.
api:user:email-already-verified	400 · id	This email address is already verified. You can sign in.

Signing up and signing in

Signing up a new tenant (POST /tenants/register), joining one (POST /users/register), and signing in with a password.

Code	Status	What it means	What to do
api:auth:email-not-verified	400 · EmailAddress	Your email address hasn’t been verified yet.	Open the verification link we emailed you, then sign in.
api:tenant:register:code-not-found	400 · code	Sign-up without an invitation isn’t open. If someone has invited you, open the invitation link in your email.
api:tenant:register:email-domain-blocked	400 · emailAddress	Sign-up isn’t open to this email domain.	Use a different address.
api:tenant:register:email-in-use	400 · emailAddress	This email address has already been used to sign up.	Sign in instead.
api:tenant:register:invite-code-mismatch-required	400 · inviteId	The invite and the invitation code don’t match.
api:tenant:register:invite-email-mismatch	400 · emailAddress	The invite was sent to a different email address.
api:tenant:register:invite-not-found	400 · inviteId	The invite doesn’t exist, or has been used or cancelled.
api:tenant:register:invite-not-valid-for-new-tenant-registration	400 · inviteId	The invite is to join an existing tenant, not to sign up a new one.	Join with POST /users/register instead.
api:tenant:register:sign-up-closed	400 · emailAddress	Sign-up isn’t open here.	Ask a tenant admin to invite you.
api:tenant:register:verification-failed	400 · turnstileToken	We couldn’t confirm you’re not a robot.	Complete the check again, then sign up.
api:user:register:email-in-use	400 · emailAddress	An account already exists for this email address.	Sign in instead.
api:user:register:invite-email-mismatch	400 · emailAddress	This invitation was sent to a different email address.
api:user:register:invite-not-found	400 · inviteId	This invitation is no longer valid.
api:user:register:invite-not-valid-for-joining-tenant-registration	400 · inviteId	This invitation can’t be used to join a tenant.

Signing in with a provider

Signing in, or signing up, with an identity provider runs in the browser. When it fails, the browser is sent back to the portal with the code in the error query parameter (“Redirect” below). Finishing a sign-in (POST /auth/sso/exchange), and linking or unlinking a provider, answer with the code instead.

Code	Status	What it means	What to do
api:auth:sso:account-disabled	400	The account is disabled.	Ask an admin of your team to enable it.
api:auth:sso:account-not-verified	400 · code	The account’s e-mail address hasn’t been verified.	Open the verification link we emailed you, then sign in.
api:auth:sso:browser-mismatch	Redirect	The provider came back to a browser other than the one that started the sign-in.	Start it again in the browser you want to use.
api:auth:sso:cancelled	Redirect	The person cancelled at the provider (or refused consent).
api:auth:sso:email-domain-blocked	Redirect	Signing up: the address’s domain can’t be used to sign up.	Use an account with a different address.
api:auth:sso:email-in-use	Redirect	Signing up: the address, or a variant of it, is in use or has signed up before.	Sign in instead.
api:auth:sso:email-not-verified	400 · code	Signing up: the provider didn’t say the identity’s e-mail address is verified.	Verify it with the provider, then try again.
api:auth:sso:exchange-failed	Redirect	The provider’s code couldn’t be redeemed, or what it returned couldn’t be trusted.	Try again.
api:auth:sso:identity-linked-to-another-account	400 · provider	The identity is linked to another account.	Unlink it there first, or use another one.
api:auth:sso:interactive-session-required	403	Only a person’s own signed-in session can change how they sign in: not an API key or a run’s token.
api:auth:sso:invalid-code	400 · code	The one-time code is unknown, expired, used, for another purpose, or doesn’t match the verifier.	Start it again.
api:auth:sso:invalid-link-token	400 · token	The link-confirmation link is unknown, expired, used or wrong.
api:auth:sso:invalid-request	Redirect	A start without a valid codeChallenge, or with an unknown intent.	Try again.
api:auth:sso:invalid-state	Redirect	The provider came back with a state that is missing, unknown, expired, already used or another provider’s.	Start it again.
api:auth:sso:last-sign-in-method	400 · provider	The identity is the account’s only way to sign in, so it can’t be unlinked.	Set a password or link another provider before you remove it.
api:auth:sso:link-confirmation-required	Redirect	The identity’s verified address is an existing account’s, which isn’t linked to it: nothing is linked automatically, and the account’s owner has been e-mailed a link to confirm it.
api:auth:sso:no-account	Redirect	Signing in: no account is linked to the identity, and none has its verified address.	Sign in another way, or use the account you joined with.
api:auth:sso:no-pending-link	400 · pendingLink	There is no link waiting for confirmation.
api:auth:sso:provider-already-linked	400	The account already has an identity at that provider; unlink it first.	Unlink it before linking a different one.
api:auth:sso:provider-error	Redirect	The provider came back with an error, or without a code.	Try again in a moment.
api:auth:sso:provider-not-enabled	Redirect	The provider isn’t one Maitento knows, or isn’t set up on this deployment.	Use another way to sign in.
api:auth:sso:provider-not-linked	400 · provider	The account has no identity at that provider.
api:auth:sso:resend-too-soon	400 · pendingLink	A confirmation e-mail was sent moments ago; wait before asking for another.	Wait a few minutes before asking for another.
api:auth:sso:sign-up-closed	Redirect	Signing up: sign-up isn’t open.	Ask a tenant admin to invite you.
api:auth:sso:unknown-provider	400 · provider	The provider named isn’t one Maitento knows.

Notifications

The live notification feed (GET /notifications).

Code	Status	What it means	What to do
api:notifications:invalid-scope	400 · scope	The scope isn’t user or tenant.

Cloud shell

Opening the portal’s cloud shell.

Code	Status	What it means	What to do
api:shell:process-token-refused	403	The cloud shell was asked for with a run’s token. Only your own signed-in session can open it.
api:shell:too-many-pending-tickets	400 · ticket	Too many cloud shell connections are being opened at once.	Wait a moment and try again.