Error codes

Every Unkey error has a code shaped like err:{system}:{category}:{specific}, and every code has a page here at /errors/{system}/{category}/{specific}. Each page tells you what the error means, shows an example response, and lists the likely causes and how to fix them.

Reading an error code

The first part tells you where the error came from.

System	Meaning	Returned by
`user`	Your request can’t be processed as sent: a malformed body, a query that breaks a rule, or a rate limit you went over.	The API at `api.unkey.com`
`unkey`	The API understood the request but couldn’t complete it: authentication, permissions, a missing or conflicting resource, a failed precondition, or a failure on our side.	The API at `api.unkey.com`
`frontline`	The gateway in front of an app on Compute rejected a request or couldn’t forward it. Often the person who sees it is calling your API, not you.	The gateway on your app’s domains

The second part groups codes by kind, and the third names the exact problem. Always read the whole code, because some names appear in two categories. err:unkey:authentication:key_not_found is about the root key you authenticated with. err:unkey:data:key_not_found is about a key you referenced in the request.

What the API error body looks like

The API returns errors as JSON:

meta.requestId identifies the request. Include it when you contact support.
error.type is the error’s page in this catalog.
error.status repeats the HTTP status.
error.title is a short label. Match on error.type, never on the title.
error.detail explains what went wrong this time, often with the exact value or permission.

Not found

{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "error": {
    "detail": "We could not find the requested key.",
    "status": 404,
    "title": "Not Found",
    "type": "/errors/unkey/data/key_not_found"
  }
}

Validation failures (err:unkey:application:invalid_input) add an errors array. Each entry has a location, such as /required, and a message, such as missing property 'apiId'. Some entries also have a fix that says what to change.

Validation failure

{
  "meta": {
    "requestId": "req_8f7g6h5j4k3l2m1n"
  },
  "error": {
    "detail": "POST request body for '/v2/keys.createKey' failed to validate schema",
    "errors": [
      {
        "location": "/required",
        "message": "missing property 'apiId'"
      }
    ],
    "status": 400,
    "title": "Bad Request",
    "type": "/errors/unkey/application/invalid_input"
  }
}

Don’t guess the status from the code’s name. Every err:unkey:data:*_not_found code is 404, but err:unkey:authentication:key_not_found and err:unkey:authentication:portal_session_not_found are 401, because what’s missing is your credential. A 5xx status means the failure is on our side, not in your request. Retry with backoff if the request is safe to repeat, and contact support with the request ID if it keeps happening.

What the gateway error body looks like

The gateway in front of apps on Compute returns a smaller body: a request ID, a code, and a message. Each error’s page gives its status.

Gateway error

{
  "meta": {
    "requestId": "req_3k2j1h0g9f8e7d6c"
  },
  "error": {
    "code": "err:frontline:client:invalid_key",
    "message": "Authentication failed. The provided API key is invalid."
  }
}

You get this JSON when your request asks for it: an Accept header of application/json, application/*, or */* without text/html. Plain curl sends */*, so it gets JSON. Everything else, including a browser, gets an HTML page with the same code, message, and request ID.

Authentication

The root key or session token is missing, malformed, or unknown. Platform.

Authorization

You are identified but not allowed: missing permission, disabled key or workspace, expired key. Platform.

Data

A resource does not exist, was deleted, or already exists. API Management and Compute.

Application

Validation beyond the schema, preconditions including the deployment lifecycle, delete protection, and failures on our side.

Limits

A plan allowance is exhausted. Today that only covers Compute custom domains.

User errors

Bad request

Body size, timeouts, disconnects, permission query syntax, and analytics query rules.

Unprocessable entity

An analytics query was valid but exceeded its time, memory, or row budget.

Too many requests

The analytics query quota.

Gateway errors

Client

The request to your app was rejected by a gateway policy: missing or invalid key, permissions, rate limit, firewall, schema.

Capacity

The deployment is offline, has no running instances, or the workspace reached its spend limit.

Routing

No deployment or configuration matches the requested host.

Upstream

Your app did not answer, answered badly, or took too long.

Config

The gateway configuration for the deployment is invalid.

Platform

The gateway failed on our side.

Get started

Workspace

Audit logs

Billing

Root keys

API

CLI

AI coding

Security

Errors

Reading an error code

What the API error body looks like

What the gateway error body looks like

Categories

Unkey errors

Authentication

Authorization

Data

Application

Limits

User errors

Bad request

Unprocessable entity

Too many requests

Gateway errors

Client

Capacity

Routing

Upstream

Config

Platform

​Reading an error code

​What the API error body looks like

​What the gateway error body looks like

​Categories

​Unkey errors

Authentication

Authorization

Data

Application

Limits

​User errors

Bad request

Unprocessable entity

Too many requests

​Gateway errors

Client

Capacity

Routing

Upstream

Config

Platform

Reading an error code

What the API error body looks like

What the gateway error body looks like

Categories

Unkey errors

User errors

Gateway errors