Home
Guides

Handling Missing or Invalid Tokens

We recommend returning consistent and predictable error responses when:

  • A token is missing
  • A token is invalid
  • A payment token (pay or kya-pay) does not have sufficient balance

Clear error semantics improve developer experience and agent interoperability.


Status Code Guidelines

ScenarioRecommended Status
Missing token403 Forbidden
Invalid token (expired or signature/verification failure)401 Unauthorized
Insufficient balance402 Payment Required

If You Require kya tokens

Missing

Return an HTTP 403 Status Code

Response body:

Missing KYA token in the skyfire-pay-id 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 skyfire-pay-id header.

Invalid

Return an HTTP 401 Status Code

Response body:

Invalid KYA token in the skyfire-pay-id 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 skyfire-pay-id header.

If You Require pay tokens

Missing

Return an HTTP 403 Status Code

Response body:

Missing Pay token in the skyfire-pay-id 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 skyfire-pay-id header.

Invalid

Return an HTTP 401 Status Code

Response body:

Invalid Pay token in the skyfire-pay-id 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 skyfire-pay-id header.

Insufficient Balance

Return an HTTP 402 Status Code

Response body:

The balance on the given 'pay' token is not enough. Please create and send a new "pay" token.

If You Require kya-pay tokens

Missing

Return an HTTP 403 Status Code

Response body:

Missing KYAPay token in the skyfire-pay-id 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 skyfire-pay-id header.

Invalid

Return an HTTP 401 Status Code

Response body:

Invalid KYAPay token in the skyfire-pay-id 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 skyfire-pay-id header.

Insufficient Balance

Return an HTTP 402 Status Code

Response body:

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 .

Response Formatting

Plain Text

If the caller is likely a Web Scraper, return the above messages 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

We recommend adding an llms.txt file to your website explaining:

  • That your service requires Skyfire tokens
  • The required header (skyfire-pay-id)
  • The expected token types (kya, pay, kya-pay)
  • Where to obtain tokens

Learn more:
https://llmstxt.org/