Error codes

Every error from the koigrid API and MCP has the same shape: a stable `error` code, a readable `detail`, `issues` (field and reason) when validation fails, a `requestId` (also in the X-Request-Id header, quote it to support), `retryable` (whether repeating the same request can succeed) and a `docUrl` pointing here. This list is generated from the catalog in code.

Response shape

HTTP/1.1 400 Bad Request
X-Request-Id: 3f2a…

{
  "error": "bad_request",
  "detail": "image: image repository name must be lowercase",
  "issues": [{ "path": "image", "message": "image repository name must be lowercase", "code": "custom" }],
  "requestId": "3f2a…",
  "retryable": false,
  "docUrl": "https://koigrid.com/docs/error-codes#bad_request"
}
CodeMeaningWhat to doRetry
already_appliedThere is already an application for this account.Check the existing one instead of applying again.—
already_existsThe destination already exists.Choose another destination, or repeat with overwrite: true.—
already_memberThat person is already a member.Nothing to do.—
already_reviewedIt has already been reviewed.Nothing to do.—
analyze_in_progressAn ANALYZE of this database is already running.Its result appears as `db.analyze.done` in the activity feed.✓
app_deletedThe app was deleted while it was being deployed.Restore it from the trash or create it again.—
app_not_foundThe deployment's app no longer exists.Create the app again and deploy it.—
app_pausedThe app is paused.Resume it (or top up the balance if it was paused for that reason).—
app_sleepingThe app is asleep (no visits for a while) and this request did not wake it: it came from a security scanner.Visit the app from a browser or any normal client; that visit wakes it up.—
app_wakingThe app was asleep and is starting.Retry after the seconds in the `Retry-After` header.✓
backups_expiredThe backups of this database have expired.It can no longer be restored; `expiredAt` says when.—
bad_headersThe headers are not valid.Pass them as an object of names to values.—
bad_requestThe request is not valid for this resource.Read `detail` (and `issues` if present), fix the request and send it again.—
billing_disabledPayments are not configured on this koigrid deployment.Contact support.—
billing_unavailablePayments are not configured on this koigrid installation.Contact support.—
bucket_too_smallThe bucket is too small for that time range.Use a larger bucket or a shorter range.—
budget_exceededThe spend limit (organization or token) has been reached.Raise the limit in Spend Management or wait for the next month.—
build_export_failedThe build finished but exporting the image was cut off (runner I/O, not your code).Trigger the deployment again.✓
build_push_failedThe image was built but could not be stored in the registry.Read the deployment logs; if they point to koigrid, trigger it again.—
busyAnother test is already running.Wait for it to finish, then repeat.✓
canary_invalidoOperator endpoint: not a valid canary request.Operator only.—
cannot_change_ownerThe owner role cannot be changed this way.Transfer the ownership instead.—
cap_reachedThe cap of that reward is reached.Nothing to do until it resets.—
capacity_unavailableThere is no room for this resource on the fleet right now.Retry later or choose a smaller size; nothing was created.✓
card_requiredThis needs a saved payment method (also: the first resource of a new organization). Saving it charges nothing; the first card opens a 7-day free trial (up to 2 GB of RAM).Add a card (POST /billing/checkout-session, MCP add_payment_method), have a person open the link, and repeat.—
command_not_foundThat background command does not exist on this VM (or the VM was deleted).List them with GET /api/v1/sandboxes/vms/:id/commands.—
conflictThe request conflicts with the current state of the resource.Read the resource again and retry with the current state.—
cost_escalationA credential cannot get a higher cost cap than the token that creates it.Ask for a cap equal to or lower than yours.—
create_failedThe resource was created but failed to start.Read `detail`, fix it and create it again.—
deploy_exceptionThe deployment stopped on an unexpected error on our side.Trigger it again; if it persists, contact support.✓
deploy_in_progressAnother deployment of this app is running.Wait for it to finish and retry.✓
deploy_turno_agotadoThe deployment waited too long for its turn.Trigger the deployment again.✓
destino_desconocidoOperator operation: unknown destination server.Operator only.—
directory_not_emptyThe directory is not empty.Repeat with recursive=true to delete it and everything inside.—
disco_sin_medirOperator operation: the disk could not be measured.Operator only: repeat.✓
dns_sin_medirOperator operation: the DNS could not be measured.Operator only: repeat.✓
dominio_no_reservadoOperator endpoint: the account is outside the reserved canary domain.Operator only.—
dr_copy_failedOperator operation: the disaster-recovery copy failed.Operator only: read the event and repeat.✓
duplicateIt was already submitted.Nothing to do.—
edge_sync_failedThe new version could not be published to the edge.Trigger the deployment again; the previous version keeps serving.✓
email_mismatchThe invitation is for another email address.Sign in with the invited address.—
emptyThe file is empty.Upload a file with content.—
environment_unreadableThe stored environment of this VM could not be decrypted.Set it again with PUT /api/v1/sandboxes/vms/:id/environment.—
es_liderOperator operation: that member is the leader.Operator only: switch over first.—
es_masterOperator operation: that copy is now the master.Operator only.—
existsSomething with that key or name already exists.Use another key or name, or edit the existing one.—
expiredIt has expired.Ask for a new one.—
fair_use_limitThis exceeds the fair-use ceiling for an account (lower for a new account until its first payment).Contact support if you need more; a new account can also add credit (POST /billing/wallet/topup).—
file_operation_failedThe file operation failed inside the VM.Read `detail` (the message from inside the VM) and repeat.✓
file_too_largeThe file is larger than this operation allows (4 MB per write).Split it, or move it with exec (curl) or SSH.—
forbiddenThe credentials are valid but cannot do this.Use a token with the scope or role this action needs (see `detail`).—
forbidden_hostThat image host is not in the allow list of the project.Add the host to the image settings, then repeat.—
forma_no_activaOperator operation: this disaster-recovery copy form is not available for this database (standby is off, or the database is an already promoted copy).Operator only: create it as a member.—
free_tier_limitThe free plan limit for this resource is reached.Delete something you no longer use, or add a payment method.—
free_tier_waitlistedThe free tier is full; your organization is on the waiting list (`position`).Wait to be admitted (you get a notice), or add a payment method to skip the list.✓
fuente_obligatoriaA checked price needs the https URL it was read from.Send at least one `fuentes` entry starting with https://.—
funcion_desconocidaThat feature is not in the comparison catalogue.Use a key listed by `ops-competidor funcion registrar` (definitions in lib/comparison.ts).—
giftcard_unavailableGift cards are no longer offered; rewards are koigrid credit.Redeem as credit.—
health_unknownThe health of the new container could not be determined.Trigger the deployment again; if it repeats, read the runtime logs.✓
host_errorThe VM host could not complete the operation (our side); the VM was left as it was.Retry; if it repeats, contact support with the requestId.✓
idempotency_in_progressA request with this Idempotency-Key is still being processed.Retry with the same key in a few seconds to get its result.✓
image_pull_failedThe image could not be downloaded (it does not exist, is private without credentials, or the name is wrong).Check the image name and tag, and the registry credentials if it is private.—
image_pull_timeoutDownloading the image took longer than allowed.Trigger the deployment again; a smaller image deploys faster.✓
importe_invalidoThe amount is not valid.Use an amount within the limits in `detail`.—
insufficient_balanceThe balance is not enough.Lower the amount.—
insufficient_scopeThe connection lacks a permission this action needs.Reconnect granting the scope named in `detail`.—
internalAn unexpected error on our side.Retry; if it persists, contact support quoting `requestId`.✓
internal_registry_cred_failedkoigrid could not issue the internal registry credential (our fault, not your app).Trigger the deployment again.✓
invalidThe value or invitation is not valid.Read `detail`.—
invalid_amountThe amount is missing or not valid.Send `amountCents` as a positive integer, or null to turn it off.—
invalid_argumentsThe tool was called with arguments that do not fit together.Read `detail`: it names the missing or wrong argument.—
invalid_bodyThe body must be a JSON object.Send a JSON object (`{…}`), not an array or a scalar.—
invalid_bucketThe bucket size of the series is not valid.Use one of the sizes listed in `detail`.—
invalid_detailsThe details of the claim are missing or not valid.Read `detail` and fill them in.—
invalid_graceThe grace period is longer than allowed.`detail` gives the limit; use a shorter grace.—
invalid_grantThe grant secret is invalid or was revoked.Use a valid grant or create a new one.—
invalid_hoursThe time range in hours is not valid.Use a whole number of hours within the allowed range.—
invalid_jsonThe body is not valid JSON.Send a JSON body with `content-type: application/json`.—
invalid_manifestThe project manifest is not valid.Read `detail` and fix the manifest.—
invalid_modeThat billing mode does not exist.Use one of the modes listed in `detail`.—
invalid_nameThe name does not follow the allowed format.Use lowercase letters, digits and hyphens.—
invalid_refThe image reference or git reference is not valid.Use a lowercase image name (e.g. `nginx:1.27`) or an existing branch/commit.—
invalid_requestThe request combines options that this endpoint does not accept together.Read `detail`: it says which option to drop or which endpoint to use.—
invalid_scheduleThe cron expression is not valid.Use a standard 5-field cron expression, e.g. `*/5 * * * *`.—
invalid_scopesOne or more scopes do not exist.Use the scopes listed in /llms.txt.—
invalid_signatureThe request signature does not match.Sign the exact raw body with the shared secret.—
invalid_sizeThat VM size does not exist.Use one of the sizes listed in the API reference (small, medium, large…).—
invalid_source_urlThe download URL of the uploaded code is not valid (koigrid configuration, not your app).Trigger the deployment again; we are notified.✓
invalid_stateThe VM is not in a state that allows this operation (or another operation on it is in progress).Read its `status` (GET the VM) and retry when it allows it.—
invalid_tagThe image tag is not valid.Use a tag name (not a `sha256:` digest) for this operation.—
invalid_tokenThe token in the URL is not valid.Copy the hook URL again from the dashboard or the API.—
invalid_urlThe URL is not valid or points to a private address.Use a public https URL.—
invalid_windowThe time window is not valid.Check the start/end values and their order.—
key_requiredA key is required.Pass the object key the operation needs.—
last_ownerThe organization would be left without an owner.Make someone else owner first.—
launch_timeoutThe containers took longer than allowed to start.Trigger it again; if it repeats, check the start command and the memory.✓
limitThe maximum for this app is reached.Delete one you no longer use.—
limit_reachedThe maximum for this resource is reached.Delete one you no longer use.—
migrate_failedThe app could not be moved to another server.Read `detail`; the app keeps running where it was.—
missing_sourceThe app has no image, repository or uploaded code to deploy.Set `image` or `repo` on the app, or deploy with `--dir`.—
modo_invalidoThat billing mode does not exist.Use one of the modes listed in `detail`.—
motivo_cortoOperator operation: the reason is too short.Operator only: write why.—
nada_que_sustituirOperator operation: there is no member-form disaster-recovery copy to replace with a standby one (none, already standby, or a replacement half done).Operator only: request a normal copy, or retire the old copy of a half-done replacement first.—
name_takenAnother resource in this project already has that name.Pick another name, or delete the old one first.—
no_canary_en_cajaOperator endpoint: that product has no on-box canary.Operator only.—
no_capacityNo VM host has room for this VM right now.Retry in a few minutes, or use a smaller size.✓
no_dataThe required data parameter is missing.Pass the parameter named in `detail`.—
no_dr_copyOperator operation: there is no disaster-recovery copy.Operator only.—
no_es_canaryOperator endpoint: that account is not a canary account.Operator only.—
no_estableOperator operation: the cluster is not stable.Operator only: wait until it is.✓
no_existeOperator operation: the resource does not exist.Operator only.—
no_fileNo file was sent.Send the file in the `file` field of a multipart body.—
no_leaderThe database has no primary at this moment (failover in progress).Retry in a minute.✓
no_live_deployThis needs an app with a live deployment.Deploy an app that serves, then repeat.—
no_runnerNo server is configured to run this deployment (our side).Trigger it again later; we are notified.✓
no_runner_availableNo server has room for this app right now.Retry later or lower its memory; the app keeps serving the previous version.✓
no_seatsThere are no places left in the program.Wait for a place to free up.—
no_source_archiveThe uploaded source archive is no longer available.Upload the code again (`deploy --dir`).—
no_urlThere is no URL to test.Deploy the app first, or pass a URL.—
no_walletThere is no wallet to send the payout to.Add your wallet (network and address), then repeat.—
not_a_directoryThe path exists but is not a directory.Use the path of a directory, or read it as a file.—
not_a_fileThe path exists but is not a regular file.List it as a directory, or use the path of a file.—
not_admittedThe beta application has not been approved.Wait for the review, or check its status.—
not_configuredThis feature is not configured for your organization yet.Configure it first (see `detail`).—
not_foundThe resource does not exist, or it is not in your organization.Check the id; list the resources to find the right one.—
not_gitPreviews need an app deployed from Git.Use an app with a repository.—
not_memberThat person is not a member of the organization.Check the member id.—
not_pendingThat maintenance action is not pending on this database, so there is nothing to apply now.Read pendingMaintenance in GET /api/v1/databases/:id and apply one of the actions listed there.—
not_readyThe resource is still being created.Wait until its status is `running` and retry.✓
not_yetIt is too early for this step.`detail` says from when it opens.—
nothing_to_roll_backThere is no previous live deployment to go back to.Deploy a working version instead.—
oferta_desconocidaThat competitor offering is not in the registry.Use an id from `ops-competidor ofertas` (lib/competidores/registro.ts), or add the offering there first.—
operacion_en_cursoOperator operation: another operation is running on that resource.Operator only: wait for it.✓
org_no_encontradaThe organization was not found.Check the token: it must belong to an existing organization.—
otro_grupoOperator operation: the destination is in another pool.Operator only.—
pago_no_configuradoPayments are not configured on this koigrid installation.Contact support.—
payment_method_requiredThis needs a payment method on file.Add a card with POST /api/v1/billing/checkout-session (empty body) and retry.—
plan_concedidoThe organization has a plan granted by koigrid; nothing to pay.Nothing to do; contact support to change it.—
plan_grantedThe organization has a plan granted by koigrid; nothing to pay.Nothing to do; contact support to change it.—
plan_limitYour plan does not include more of this resource.Delete one you no longer use, or add a payment method.—
planes_retiradosPlans are retired: koigrid bills what you reserve, by the hour.Add a payment method instead of choosing a plan.—
plans_retiredPlans were replaced by per-resource pricing.Add a payment method instead (POST /billing/checkout-session with an empty body).—
port_conflictTwo deployments chose the same port at the same time.Trigger the deployment again.✓
precio_invalidoThe competitor price does not match the expected shape (ProviderPricing).Read `detail`: it names each wrong field. Unknown fields are rejected on purpose.—
project_not_foundThat project does not exist in this organization.Check the project id.—
project_scopeThe token is limited to another project.Use a token for this project or one for the whole organization.—
protected_pathThat path is protected (/, /root and system directories).Delete what is inside it instead.—
query_errorThe SQL statement failed in the database.Read `detail` (the database error) and fix the statement.—
rate_limitedToo many requests.Slow down and retry after the `Retry-After` header.✓
recursos_vivosOperator endpoint: the account still has live resources.Operator only: delete them first.—
registry_auth_failedkoigrid could not log in to the image registry with the credentials of the app.Check the registry credentials (user/token) saved on the app.—
replica_not_readyA replica started but never became ready to receive traffic.Read the runtime logs: check the port and the health check path.—
replica_unhealthyA replica failed its health check after starting.Read the runtime logs of that replica.—
resize_rejectedThis resize is not possible for the cache.Read `detail`: usually the new size is below the data it holds.—
restore_gapThat point in time falls in a window with no usable backup.Pick a time before or after the gap stated in `detail`.—
restore_out_of_rangeThat point in time is outside the restorable range of the database.Pick a time inside `restorableRange` (earliestRestorableTime → latestRestorableTime), or restore without targetTime.—
rotation_unavailablePassword rotation cannot run right now.Read `detail` and retry later.✓
runner_unreachableThe server that runs the app could not be reached (our side).Trigger the deployment again; the app keeps serving the previous version.✓
scale_out_transition_in_progressThis app is still switching its scale-out off (moving traffic to its runner and waiting for DNS caches to expire).Wait for `app.scale_out_configured` or `app.scale_out_off_incompleto` in the activity feed (a few minutes), then retry.✓
scale_out_transition_interruptedThe scale-out off transition of this app was interrupted (the process restarted mid-way); koigrid resumes it automatically.Nothing to do: watch for `app.scale_out_off_reanudado` and then `app.scale_out_configured` in the activity feed. If it does not finish, repeat PUT /apps/:id/scale-out {"enabled":false}.—
scope_escalationA token cannot create another token with more permissions than its own.Request only scopes the current token already has.—
scope_no_retiradoOperator operation: the Patroni scope is still in etcd.Operator only.—
scopes_invalidosOperator endpoint: invalid scopes for a canary token.Operator only.—
server_errorA server-side setting is missing (our side).Retry later; contact support with the requestId if it repeats.✓
sin_endpointOperator operation: the database has no write endpoint for the standby copy to follow.Operator only.—
sin_organizacionOperator endpoint: the account has no organization.Operator only.—
sin_sitioOperator operation: no room on the destination.Operator only.—
sin_tarjetaThis needs a saved payment method.Add a card (POST /billing/checkout-session) and repeat.—
too_bigThe test asks for more than allowed.Lower the rate or the duration (limits in `detail`).—
too_largeThe payload is larger than allowed.Send a smaller file or split it.—
too_longA value is longer than allowed.Shorten it to the limit stated in `detail`.—
too_many_pointsThat range and bucket give too many points.Use a larger bucket or a shorter range.—
tool_failedThe tool could not complete the action.Read `detail`; if it looks like our fault, contact support with the requestId.—
transfer_failedThe VM could not download or upload the file through the signed URL.Repeat; if it keeps failing, check the VM has network access (exec: curl -I https://storage.koigrid.com).✓
unauthorizedMissing or invalid credentials.Send `Authorization: Bearer <token>` with a valid, unexpired token.—
unavailableThe service is temporarily unavailable.Retry later.✓
unhealthyThe container started but did not pass its health check.Read the runtime logs: check the port it listens on and the health check path.—
unknown_lineThat reward line does not exist or is disabled.Use one listed by GET /rewards/lines.—
unknown_memberThat member is not part of this database.Use one of the names in members[] of the response (the Patroni names in GET /databases/:id).—
unresolved_referenceA value of the environment references a secret or resource that does not exist in this project (or is not ready).Fix the ${{…}} named in `detail`: create the shared variable with PUT /api/v1/config, or use the exact name of the database, cache or app.—
unsafe_for_third_partiesThe environment has safeForThirdParties on, so it cannot carry anything of yours (no ${{…}} references).Remove the references named in `detail` and pass literal values, or turn safeForThirdParties off.—
upload_missingNothing was uploaded to that uploadUrl yet.PUT the file to uploadUrl first, then call upload-complete.—
upstream_errorThe origin server answered with an error.Check the source URL; retry later.✓
usage_not_verifiedkoigrid has no record of the usage this claim needs.Use the product first (a live deployment), then claim.—
validation_failedOne or more fields failed validation.Each entry in `issues` names the field (`path`) and why; fix those fields.—
valor_invalidoFeature value must be yes, partial, no or na.Send one of: yes | partial | no | na.—
vm_not_readyThe VM is paused, stopped or failed, so it cannot run this; it will not change by itself.Resume (paused) or start (stopped) it first; the `detail` says which.—
vm_scopeThis token is scoped to one VM and only works on that VM's endpoints.Use /api/v1/sandboxes/vms/<its VM>/…, or a token of the organization for anything else.—
vm_setting_upThe VM is still running a blocking setup script of its environment; the request waited 60 s.Follow it with GET /api/v1/sandboxes/vms/:id/commands/<commandId>/stream (the `detail` has the commandId), or retry in a few seconds.✓
vm_startingThe VM is still booting or resuming; the request waited 60 s and it was not ready yet.Retry the same request in a few seconds.✓
vms_unavailableAgent VMs cannot be created right now (no VM host available, or new VMs are closed for maintenance). Existing VMs are untouched.Retry later, or use Sandboxes (POST /api/v1/sandboxes) meanwhile; write to support if it lasts.—