> For the complete documentation index, see [llms.txt](https://docs.hypersolutions.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hypersolutions.co/api-reference/errors.md).

# Errors

Every reason the API refuses a request, with its status code, error code and how to fix it.

When the API refuses a request because of your API key, plan, balance or domain whitelist, it answers with a status code and a JSON body naming the reason:

```json
{
  "error": "Your account has no active akamai plan and no pay-as-you-go balance.",
  "code": "no_plan_or_balance",
  "docs": "https://docs.hypersolutions.co/api-reference/errors#no_plan_or_balance"
}
```

* `error` is a readable message. The SDKs show it as the error text, for example `API returned with error: Your account has no active akamai plan and no pay-as-you-go balance.`
* `code` is stable. Match on it rather than on the message, which can be reworded.
* `docs` links to the entry for that code on this page.

| Status | Meaning                                                                              |
| ------ | ------------------------------------------------------------------------------------ |
| `401`  | The credentials are missing or wrong: API key, organization key or signature.        |
| `402`  | The key is valid but there is no plan or pay-as-you-go balance to serve the request. |
| `403`  | The key is valid but not allowed to make this request: disabled, product or domain.  |

Errors about the request body itself (for example a missing `pageUrl`) are documented on each product's API reference page.

## 401: credentials

### missing\_api\_key <a href="#missing_api_key" id="missing_api_key"></a>

The request has no `x-api-key` header. Add it with your API key, see [Authentication](https://docs.hypersolutions.co/api-reference/authentication.md).

### malformed\_api\_key <a href="#malformed_api_key" id="malformed_api_key"></a>

The `x-api-key` header is not an API key. API keys are UUIDs (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`); check that the whole key was copied without spaces or quotes.

### invalid\_api\_key <a href="#invalid_api_key" id="invalid_api_key"></a>

No API key with this value exists. Copy the key again from [hypersolutions.co/keys](https://hypersolutions.co/keys).

### missing\_signature <a href="#missing_signature" id="missing_signature"></a>

The key has JWT signing enforced but the request has no `x-signature` header. Generate one as shown in [Authentication](https://docs.hypersolutions.co/api-reference/authentication.md).

### invalid\_signature <a href="#invalid_signature" id="invalid_signature"></a>

The `x-signature` header does not verify. The message says why, for example an expired token: signatures are short-lived, so generate a fresh one for every request, signed with the key's JWT secret and with the API key in the `key` claim.

### missing\_app\_signature <a href="#missing_app_signature" id="missing_app_signature"></a>

The request has an `x-app-key` header but no `x-app-signature`. Organization requests need both, see [Authentication](https://docs.hypersolutions.co/api-reference/authentication.md).

This code, `invalid_app_key`, `invalid_app_signature` and `not_organization_member` are also returned by the [Usage API](https://docs.hypersolutions.co/api-reference/usage-statistics.md#checking-a-key-for-an-organization) when it is called with organization headers.

### invalid\_app\_key <a href="#invalid_app_key" id="invalid_app_key"></a>

No organization has this `x-app-key`.

### invalid\_app\_signature <a href="#invalid_app_signature" id="invalid_app_signature"></a>

The `x-app-signature` header does not verify against the organization's app secret, or it has expired.

## 402: plan and balance

A request is served from an active plan for the product it calls, or else from your pay-as-you-go balance. These codes say which of the two ran out.

### no\_plan\_or\_balance <a href="#no_plan_or_balance" id="no_plan_or_balance"></a>

Your account has no active plan for this product and no pay-as-you-go balance. This is also the answer when you have a plan for a different product only, for example a DataDome plan used for Akamai requests. Buy a plan for the product or top up your balance at [hypersolutions.co](https://hypersolutions.co).

### plan\_exhausted <a href="#plan_exhausted" id="plan_exhausted"></a>

Your plan for this product has used all of its requests and there is no pay-as-you-go balance to continue with. Upgrade the plan, wait for it to renew, or top up your balance.

### plan\_expired <a href="#plan_expired" id="plan_expired"></a>

Your plan for this product has expired and there is no pay-as-you-go balance to continue with. Renew the plan or top up your balance.

### balance\_exhausted <a href="#balance_exhausted" id="balance_exhausted"></a>

Your pay-as-you-go balance is used up and there is no active plan for this product. Top up your balance or buy a plan.

### balance\_expired <a href="#balance_expired" id="balance_expired"></a>

Pay-as-you-go balance is valid for one year after purchase, and what is left of yours is older than that. There is no active plan for this product. Top up your balance or buy a plan.

{% hint style="info" %}
**Using API access provided by an organization?** Requests sent with an organization's `x-app-key` use your own plan or balance, and access you have through an organization only applies to requests sent by that organization's software. If your account has no products of its own, requests you send without the organization's headers are refused with `no_plan_or_balance` or `product_not_enabled`; the message says so.
{% endhint %}

## 403: access

### api\_key\_disabled <a href="#api_key_disabled" id="api_key_disabled"></a>

The API key is disabled. Enable it or create a new one at [hypersolutions.co/keys](https://hypersolutions.co/keys).

### product\_not\_enabled <a href="#product_not_enabled" id="product_not_enabled"></a>

You have a plan or balance, but your account does not have access to this product. Contact support to enable it.

### not\_organization\_member <a href="#not_organization_member" id="not_organization_member"></a>

The request has an organization's `x-app-key`, but the account the API key belongs to is not a member of that organization.

### organization\_product\_not\_enabled <a href="#organization_product_not_enabled" id="organization_product_not_enabled"></a>

The organization in `x-app-key` does not have access to this product.

### no\_domains\_whitelisted <a href="#no_domains_whitelisted" id="no_domains_whitelisted"></a>

Your account (or, with organization headers, the organization) has no whitelisted domains for this product, so no target site is allowed. Domains are whitelisted per product: a domain whitelisted for one product does not count for another. Request a domain whitelist for this product from the dashboard.

### domain\_not\_whitelisted <a href="#domain_not_whitelisted" id="domain_not_whitelisted"></a>

The target domain is not on your whitelist for this product. The message names the domain that was checked, taken from the page URL in the request, for example `Domain "www.example.com" is not whitelisted for this API key.`

Two things to check:

* **Product:** domains are whitelisted per product, so a domain whitelisted for Akamai is not whitelisted for Kasada.
* **Exact domain:** whitelisting `example.com` does not cover `www.example.com`. A wildcard like `*.example.com` covers `example.com` itself and every subdomain of it.

Make sure the domain in the message is on your whitelist for the product you are calling, or request it from the dashboard.

### access\_denied <a href="#access_denied" id="access_denied"></a>

The request was refused but the reason could not be determined at that moment, for example right after a purchase while your access is being updated. Retry after a few seconds. If it persists, contact support with the time of the request.
