Handling Missing or Invalid Tokens

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

Recommended responses by token type

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 `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.

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.

llms.txt recommendation

Add an llms.txt 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.