---
updatedAt: 2026-09-24T19:07:14.000Z
agentTools:
  projectIndex: https://docs.skyfire.xyz/llms.txt
---

# Handling Missing or Invalid Tokens

Recommended status codes and response bodies for missing, invalid, or underfunded Skyfire tokens, by token type.

Return consistent, predictable error responses when a token is missing, invalid, or, for payment tokens, underfunded. Clear error semantics improve developer experience and agent interoperability.

## Status code guidelines

| Scenario                                                         | Recommended status     |
| ---------------------------------------------------------------- | ---------------------- |
| Token is **missing**                                             | `401 Unauthorized`     |
| Token is **invalid** (expired or signature/verification failure) | `403 Forbidden`        |
| Token has **insufficient balance**                               | `402 Payment Required` |

## Recommended responses by token type

<Tabs>
  <Tab title="kya">
    **Missing.** Return `401 Unauthorized`.

    ```
    Missing `kya` token in the `kyapay-token` header. Please create an account at https://app.skyfire.xyz and create a `kya` token: https://docs.skyfire.xyz/reference/create-token. Include the token in your request in the `kyapay-token` header.
    ```

    **Invalid.** Return `403 Forbidden`.

    ```
    Invalid `kya` token in the `kyapay-token` header. Please create an account at https://app.skyfire.xyz and create a `kya` token: https://docs.skyfire.xyz/reference/create-token. Include the token in your request in the `kyapay-token` header.
    ```
  </Tab>

  <Tab title="pay">
    **Missing.** Return `401 Unauthorized`.

    ```
    Missing `pay` token in the `kyapay-token` header. Please create an account at https://app.skyfire.xyz and create a `pay` token: https://docs.skyfire.xyz/reference/create-token. Include the token in your request in the `kyapay-token` header.
    ```

    **Invalid.** Return `403 Forbidden`.

    ```
    Invalid `pay` token in the `kyapay-token` header. Please create an account at https://app.skyfire.xyz and create a `pay` token: https://docs.skyfire.xyz/reference/create-token. Include the token in your request in the `kyapay-token` header.
    ```

    **Insufficient balance.** Return `402 Payment Required`.

    ```
    The balance on the given `pay` token is not enough. Please create and send a new `pay` token.
    ```
  </Tab>

  <Tab title="kya-pay">
    **Missing.** Return `401 Unauthorized`.

    ```
    Missing `kya-pay` token in the `kyapay-token` header. Please create an account at https://app.skyfire.xyz and create a `kya-pay` token: https://docs.skyfire.xyz/reference/create-token. Include the token in your request in the `kyapay-token` header.
    ```

    **Invalid.** Return `403 Forbidden`.

    ```
    Invalid `kya-pay` token in the `kyapay-token` header. Please create an account at https://app.skyfire.xyz and create a `kya-pay` token: https://docs.skyfire.xyz/reference/create-token. Include the token in your request in the `kyapay-token` header.
    ```

    **Insufficient balance.** Return `402 Payment Required`.

    ```
    The balance on the given `kya-pay` token is not enough. Please create and send a new `kya-pay` token: https://docs.skyfire.xyz/reference/create-token.
    ```
  </Tab>
</Tabs>

> Older integrations may reference the `skyfire-pay-id` header instead of `kyapay-token`. It is deprecated and being replaced.

## Response formatting

* **Plain text.** If the caller is likely a web scraper, return the messages above in plain text.
* **Structured JSON (recommended for LLMs).** If the caller is an LLM or MCP client, return structured JSON following [MCP error conventions](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#error-handling).

## llms.txt recommendation

Add an [llms.txt](https://llmstxt.org/) file to your website explaining that your service requires Skyfire tokens, the required header (`kyapay-token`), the expected token types (`kya`, `pay`, `kya-pay`), and where to obtain tokens.