Errors

Error format, status codes, and troubleshooting.

All errors return a JSON object with an error field.

Error format

{
  "error": "Human-readable error message."
}

Status codes

Code	Meaning	When
200	OK	Successful request
201	Created	API key generated successfully
400	Bad Request	Invalid parameters (e.g. bad candle resolution, missing q param)
401	Unauthorized	Missing or malformed API key
403	Forbidden	API key is invalid or inactive
404	Not Found	Market, wallet, or token not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error
503	Service Unavailable	Service temporarily unavailable

Common errors

Missing API key

401

{
  "error": "Missing or invalid API key. Use x-api-key header or ?key= param."
}

Fix: Include your API key as a header (x-api-key: pn_live_...) or query parameter (?key=pn_live_...).

Invalid API key

403

{
  "error": "Invalid or inactive API key."
}

Fix: Verify your key is correct. Keys cannot be retrieved after creation — generate a new one if lost.

Rate limited

429

{
  "error": "Rate limit exceeded. Retry after 1772500060."
}

Fix: Wait until the timestamp, or reduce request frequency. Default limit is 120 requests per minute.

Market not found

404

{
  "error": "Market 0x123... not found"
}

Fix: Verify the token ID. Use /v1/search to find the correct token.

Invalid resolution

400

{
  "error": "Invalid resolution. Use: 1m, 5m, 15m, 1h, 4h, 1d"
}

Missing search query

400

{
  "error": "Missing required query parameter 'q'"
}

Key generation rate limit

429

{
  "error": "Too many key generation requests. Max 3 per hour."
}

WebSocket disconnections

The server may close your WebSocket connection for any of these reasons:

Reason	Trigger	What to do
Pong timeout	No Pong response for 90 seconds (3 missed Ping frames)	Ensure your read loop is not blocked — standard WS libraries handle Pong automatically
Send buffer full	Client is consuming messages too slowly	Increase processing speed or reduce subscription scope with filters
Invalid API key	Key rejected during connection upgrade	Verify your pn_live_ key is correct and active
Server restart	API binary redeployed or service restarted	Reconnect with exponential backoff (see best practices)

In all cases, the server closes the connection without a close frame. Implement reconnection with exponential backoff as described in the WebSocket overview.