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"
}| Code | Meaning | What to do | Retry |
|---|---|---|---|
already_applied | There is already an application for this account. | Check the existing one instead of applying again. | — |
already_exists | The destination already exists. | Choose another destination, or repeat with overwrite: true. | — |
already_member | That person is already a member. | Nothing to do. | — |
already_reviewed | It has already been reviewed. | Nothing to do. | — |
analyze_in_progress | An ANALYZE of this database is already running. | Its result appears as `db.analyze.done` in the activity feed. | ✓ |
app_deleted | The app was deleted while it was being deployed. | Restore it from the trash or create it again. | — |
app_not_found | The deployment's app no longer exists. | Create the app again and deploy it. | — |
app_paused | The app is paused. | Resume it (or top up the balance if it was paused for that reason). | — |
app_sleeping | The 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_waking | The app was asleep and is starting. | Retry after the seconds in the `Retry-After` header. | ✓ |
backups_expired | The backups of this database have expired. | It can no longer be restored; `expiredAt` says when. | — |
bad_headers | The headers are not valid. | Pass them as an object of names to values. | — |
bad_request | The request is not valid for this resource. | Read `detail` (and `issues` if present), fix the request and send it again. | — |
billing_disabled | Payments are not configured on this koigrid deployment. | Contact support. | — |
billing_unavailable | Payments are not configured on this koigrid installation. | Contact support. | — |
bucket_too_small | The bucket is too small for that time range. | Use a larger bucket or a shorter range. | — |
budget_exceeded | The spend limit (organization or token) has been reached. | Raise the limit in Spend Management or wait for the next month. | — |
build_export_failed | The build finished but exporting the image was cut off (runner I/O, not your code). | Trigger the deployment again. | ✓ |
build_push_failed | The image was built but could not be stored in the registry. | Read the deployment logs; if they point to koigrid, trigger it again. | — |
busy | Another test is already running. | Wait for it to finish, then repeat. | ✓ |
canary_invalido | Operator endpoint: not a valid canary request. | Operator only. | — |
cannot_change_owner | The owner role cannot be changed this way. | Transfer the ownership instead. | — |
cap_reached | The cap of that reward is reached. | Nothing to do until it resets. | — |
capacity_unavailable | There is no room for this resource on the fleet right now. | Retry later or choose a smaller size; nothing was created. | ✓ |
card_required | This 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_found | That background command does not exist on this VM (or the VM was deleted). | List them with GET /api/v1/sandboxes/vms/:id/commands. | — |
conflict | The request conflicts with the current state of the resource. | Read the resource again and retry with the current state. | — |
cost_escalation | A credential cannot get a higher cost cap than the token that creates it. | Ask for a cap equal to or lower than yours. | — |
create_failed | The resource was created but failed to start. | Read `detail`, fix it and create it again. | — |
deploy_exception | The deployment stopped on an unexpected error on our side. | Trigger it again; if it persists, contact support. | ✓ |
deploy_in_progress | Another deployment of this app is running. | Wait for it to finish and retry. | ✓ |
deploy_turno_agotado | The deployment waited too long for its turn. | Trigger the deployment again. | ✓ |
destino_desconocido | Operator operation: unknown destination server. | Operator only. | — |
directory_not_empty | The directory is not empty. | Repeat with recursive=true to delete it and everything inside. | — |
disco_sin_medir | Operator operation: the disk could not be measured. | Operator only: repeat. | ✓ |
dns_sin_medir | Operator operation: the DNS could not be measured. | Operator only: repeat. | ✓ |
dominio_no_reservado | Operator endpoint: the account is outside the reserved canary domain. | Operator only. | — |
dr_copy_failed | Operator operation: the disaster-recovery copy failed. | Operator only: read the event and repeat. | ✓ |
duplicate | It was already submitted. | Nothing to do. | — |
edge_sync_failed | The new version could not be published to the edge. | Trigger the deployment again; the previous version keeps serving. | ✓ |
email_mismatch | The invitation is for another email address. | Sign in with the invited address. | — |
empty | The file is empty. | Upload a file with content. | — |
environment_unreadable | The stored environment of this VM could not be decrypted. | Set it again with PUT /api/v1/sandboxes/vms/:id/environment. | — |
es_lider | Operator operation: that member is the leader. | Operator only: switch over first. | — |
es_master | Operator operation: that copy is now the master. | Operator only. | — |
exists | Something with that key or name already exists. | Use another key or name, or edit the existing one. | — |
expired | It has expired. | Ask for a new one. | — |
fair_use_limit | This 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_failed | The file operation failed inside the VM. | Read `detail` (the message from inside the VM) and repeat. | ✓ |
file_too_large | The file is larger than this operation allows (4 MB per write). | Split it, or move it with exec (curl) or SSH. | — |
forbidden | The credentials are valid but cannot do this. | Use a token with the scope or role this action needs (see `detail`). | — |
forbidden_host | That image host is not in the allow list of the project. | Add the host to the image settings, then repeat. | — |
forma_no_activa | Operator 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_limit | The free plan limit for this resource is reached. | Delete something you no longer use, or add a payment method. | — |
free_tier_waitlisted | The 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_obligatoria | A checked price needs the https URL it was read from. | Send at least one `fuentes` entry starting with https://. | — |
funcion_desconocida | That feature is not in the comparison catalogue. | Use a key listed by `ops-competidor funcion registrar` (definitions in lib/comparison.ts). | — |
giftcard_unavailable | Gift cards are no longer offered; rewards are koigrid credit. | Redeem as credit. | — |
health_unknown | The health of the new container could not be determined. | Trigger the deployment again; if it repeats, read the runtime logs. | ✓ |
host_error | The 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_progress | A request with this Idempotency-Key is still being processed. | Retry with the same key in a few seconds to get its result. | ✓ |
image_pull_failed | The 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_timeout | Downloading the image took longer than allowed. | Trigger the deployment again; a smaller image deploys faster. | ✓ |
importe_invalido | The amount is not valid. | Use an amount within the limits in `detail`. | — |
insufficient_balance | The balance is not enough. | Lower the amount. | — |
insufficient_scope | The connection lacks a permission this action needs. | Reconnect granting the scope named in `detail`. | — |
internal | An unexpected error on our side. | Retry; if it persists, contact support quoting `requestId`. | ✓ |
internal_registry_cred_failed | koigrid could not issue the internal registry credential (our fault, not your app). | Trigger the deployment again. | ✓ |
invalid | The value or invitation is not valid. | Read `detail`. | — |
invalid_amount | The amount is missing or not valid. | Send `amountCents` as a positive integer, or null to turn it off. | — |
invalid_arguments | The tool was called with arguments that do not fit together. | Read `detail`: it names the missing or wrong argument. | — |
invalid_body | The body must be a JSON object. | Send a JSON object (`{…}`), not an array or a scalar. | — |
invalid_bucket | The bucket size of the series is not valid. | Use one of the sizes listed in `detail`. | — |
invalid_details | The details of the claim are missing or not valid. | Read `detail` and fill them in. | — |
invalid_grace | The grace period is longer than allowed. | `detail` gives the limit; use a shorter grace. | — |
invalid_grant | The grant secret is invalid or was revoked. | Use a valid grant or create a new one. | — |
invalid_hours | The time range in hours is not valid. | Use a whole number of hours within the allowed range. | — |
invalid_json | The body is not valid JSON. | Send a JSON body with `content-type: application/json`. | — |
invalid_manifest | The project manifest is not valid. | Read `detail` and fix the manifest. | — |
invalid_mode | That billing mode does not exist. | Use one of the modes listed in `detail`. | — |
invalid_name | The name does not follow the allowed format. | Use lowercase letters, digits and hyphens. | — |
invalid_ref | The image reference or git reference is not valid. | Use a lowercase image name (e.g. `nginx:1.27`) or an existing branch/commit. | — |
invalid_request | The request combines options that this endpoint does not accept together. | Read `detail`: it says which option to drop or which endpoint to use. | — |
invalid_schedule | The cron expression is not valid. | Use a standard 5-field cron expression, e.g. `*/5 * * * *`. | — |
invalid_scopes | One or more scopes do not exist. | Use the scopes listed in /llms.txt. | — |
invalid_signature | The request signature does not match. | Sign the exact raw body with the shared secret. | — |
invalid_size | That VM size does not exist. | Use one of the sizes listed in the API reference (small, medium, large…). | — |
invalid_source_url | The download URL of the uploaded code is not valid (koigrid configuration, not your app). | Trigger the deployment again; we are notified. | ✓ |
invalid_state | The 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_tag | The image tag is not valid. | Use a tag name (not a `sha256:` digest) for this operation. | — |
invalid_token | The token in the URL is not valid. | Copy the hook URL again from the dashboard or the API. | — |
invalid_url | The URL is not valid or points to a private address. | Use a public https URL. | — |
invalid_window | The time window is not valid. | Check the start/end values and their order. | — |
key_required | A key is required. | Pass the object key the operation needs. | — |
last_owner | The organization would be left without an owner. | Make someone else owner first. | — |
launch_timeout | The containers took longer than allowed to start. | Trigger it again; if it repeats, check the start command and the memory. | ✓ |
limit | The maximum for this app is reached. | Delete one you no longer use. | — |
limit_reached | The maximum for this resource is reached. | Delete one you no longer use. | — |
migrate_failed | The app could not be moved to another server. | Read `detail`; the app keeps running where it was. | — |
missing_source | The app has no image, repository or uploaded code to deploy. | Set `image` or `repo` on the app, or deploy with `--dir`. | — |
modo_invalido | That billing mode does not exist. | Use one of the modes listed in `detail`. | — |
motivo_corto | Operator operation: the reason is too short. | Operator only: write why. | — |
nada_que_sustituir | Operator 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_taken | Another resource in this project already has that name. | Pick another name, or delete the old one first. | — |
no_canary_en_caja | Operator endpoint: that product has no on-box canary. | Operator only. | — |
no_capacity | No VM host has room for this VM right now. | Retry in a few minutes, or use a smaller size. | ✓ |
no_data | The required data parameter is missing. | Pass the parameter named in `detail`. | — |
no_dr_copy | Operator operation: there is no disaster-recovery copy. | Operator only. | — |
no_es_canary | Operator endpoint: that account is not a canary account. | Operator only. | — |
no_estable | Operator operation: the cluster is not stable. | Operator only: wait until it is. | ✓ |
no_existe | Operator operation: the resource does not exist. | Operator only. | — |
no_file | No file was sent. | Send the file in the `file` field of a multipart body. | — |
no_leader | The database has no primary at this moment (failover in progress). | Retry in a minute. | ✓ |
no_live_deploy | This needs an app with a live deployment. | Deploy an app that serves, then repeat. | — |
no_runner | No server is configured to run this deployment (our side). | Trigger it again later; we are notified. | ✓ |
no_runner_available | No server has room for this app right now. | Retry later or lower its memory; the app keeps serving the previous version. | ✓ |
no_seats | There are no places left in the program. | Wait for a place to free up. | — |
no_source_archive | The uploaded source archive is no longer available. | Upload the code again (`deploy --dir`). | — |
no_url | There is no URL to test. | Deploy the app first, or pass a URL. | — |
no_wallet | There is no wallet to send the payout to. | Add your wallet (network and address), then repeat. | — |
not_a_directory | The path exists but is not a directory. | Use the path of a directory, or read it as a file. | — |
not_a_file | The path exists but is not a regular file. | List it as a directory, or use the path of a file. | — |
not_admitted | The beta application has not been approved. | Wait for the review, or check its status. | — |
not_configured | This feature is not configured for your organization yet. | Configure it first (see `detail`). | — |
not_found | The resource does not exist, or it is not in your organization. | Check the id; list the resources to find the right one. | — |
not_git | Previews need an app deployed from Git. | Use an app with a repository. | — |
not_member | That person is not a member of the organization. | Check the member id. | — |
not_pending | That 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_ready | The resource is still being created. | Wait until its status is `running` and retry. | ✓ |
not_yet | It is too early for this step. | `detail` says from when it opens. | — |
nothing_to_roll_back | There is no previous live deployment to go back to. | Deploy a working version instead. | — |
oferta_desconocida | That 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_curso | Operator operation: another operation is running on that resource. | Operator only: wait for it. | ✓ |
org_no_encontrada | The organization was not found. | Check the token: it must belong to an existing organization. | — |
otro_grupo | Operator operation: the destination is in another pool. | Operator only. | — |
pago_no_configurado | Payments are not configured on this koigrid installation. | Contact support. | — |
payment_method_required | This needs a payment method on file. | Add a card with POST /api/v1/billing/checkout-session (empty body) and retry. | — |
plan_concedido | The organization has a plan granted by koigrid; nothing to pay. | Nothing to do; contact support to change it. | — |
plan_granted | The organization has a plan granted by koigrid; nothing to pay. | Nothing to do; contact support to change it. | — |
plan_limit | Your plan does not include more of this resource. | Delete one you no longer use, or add a payment method. | — |
planes_retirados | Plans are retired: koigrid bills what you reserve, by the hour. | Add a payment method instead of choosing a plan. | — |
plans_retired | Plans were replaced by per-resource pricing. | Add a payment method instead (POST /billing/checkout-session with an empty body). | — |
port_conflict | Two deployments chose the same port at the same time. | Trigger the deployment again. | ✓ |
precio_invalido | The competitor price does not match the expected shape (ProviderPricing). | Read `detail`: it names each wrong field. Unknown fields are rejected on purpose. | — |
project_not_found | That project does not exist in this organization. | Check the project id. | — |
project_scope | The token is limited to another project. | Use a token for this project or one for the whole organization. | — |
protected_path | That path is protected (/, /root and system directories). | Delete what is inside it instead. | — |
query_error | The SQL statement failed in the database. | Read `detail` (the database error) and fix the statement. | — |
rate_limited | Too many requests. | Slow down and retry after the `Retry-After` header. | ✓ |
recursos_vivos | Operator endpoint: the account still has live resources. | Operator only: delete them first. | — |
registry_auth_failed | koigrid 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_ready | A replica started but never became ready to receive traffic. | Read the runtime logs: check the port and the health check path. | — |
replica_unhealthy | A replica failed its health check after starting. | Read the runtime logs of that replica. | — |
resize_rejected | This resize is not possible for the cache. | Read `detail`: usually the new size is below the data it holds. | — |
restore_gap | That 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_range | That point in time is outside the restorable range of the database. | Pick a time inside `restorableRange` (earliestRestorableTime → latestRestorableTime), or restore without targetTime. | — |
rotation_unavailable | Password rotation cannot run right now. | Read `detail` and retry later. | ✓ |
runner_unreachable | The 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_progress | This 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_interrupted | The 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_escalation | A token cannot create another token with more permissions than its own. | Request only scopes the current token already has. | — |
scope_no_retirado | Operator operation: the Patroni scope is still in etcd. | Operator only. | — |
scopes_invalidos | Operator endpoint: invalid scopes for a canary token. | Operator only. | — |
server_error | A server-side setting is missing (our side). | Retry later; contact support with the requestId if it repeats. | ✓ |
sin_endpoint | Operator operation: the database has no write endpoint for the standby copy to follow. | Operator only. | — |
sin_organizacion | Operator endpoint: the account has no organization. | Operator only. | — |
sin_sitio | Operator operation: no room on the destination. | Operator only. | — |
sin_tarjeta | This needs a saved payment method. | Add a card (POST /billing/checkout-session) and repeat. | — |
too_big | The test asks for more than allowed. | Lower the rate or the duration (limits in `detail`). | — |
too_large | The payload is larger than allowed. | Send a smaller file or split it. | — |
too_long | A value is longer than allowed. | Shorten it to the limit stated in `detail`. | — |
too_many_points | That range and bucket give too many points. | Use a larger bucket or a shorter range. | — |
tool_failed | The tool could not complete the action. | Read `detail`; if it looks like our fault, contact support with the requestId. | — |
transfer_failed | The 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). | ✓ |
unauthorized | Missing or invalid credentials. | Send `Authorization: Bearer <token>` with a valid, unexpired token. | — |
unavailable | The service is temporarily unavailable. | Retry later. | ✓ |
unhealthy | The 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_line | That reward line does not exist or is disabled. | Use one listed by GET /rewards/lines. | — |
unknown_member | That 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_reference | A 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_parties | The 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_missing | Nothing was uploaded to that uploadUrl yet. | PUT the file to uploadUrl first, then call upload-complete. | — |
upstream_error | The origin server answered with an error. | Check the source URL; retry later. | ✓ |
usage_not_verified | koigrid has no record of the usage this claim needs. | Use the product first (a live deployment), then claim. | — |
validation_failed | One or more fields failed validation. | Each entry in `issues` names the field (`path`) and why; fix those fields. | — |
valor_invalido | Feature value must be yes, partial, no or na. | Send one of: yes | partial | no | na. | — |
vm_not_ready | The 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_scope | This 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_up | The 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_starting | The 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_unavailable | Agent 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. | — |