Status Code Guidelines

Scenario	Recommended Status
Missing token	`403 Forbidden`
Invalid token (expired or signature/verification failure)	`401 Unauthorized`
Insufficient balance	`402 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/