Troubleshooting

Authentication Errors

401 Unauthorized — Invalid API Key

Your API key is missing, expired, or malformed.

• Verify the key starts with pk_live_
• Check the X-API-Key header is set (not Authorization)
• Confirm the key is still active on your API Keys page
• If you lost the key, revoke it and create a new one — full keys are only shown once

401 Unauthorized — Invalid LLM Key

Your LLM provider API key is rejected by the provider.

• Validate your key: client.validate_llm_key() (Python) or client.validateLlmKey() (TypeScript/Unity)
• Check the key has sufficient credits/quota with your LLM provider
• Ensure the model name matches the provider (e.g., gpt-4o for OpenAI, claude-sonnet-4-5-20250514 for Anthropic)

403 Forbidden — Not Owner or Persona Unpublished

SDK API keys can only access personas you own that are published.

• Confirm the persona is published (not still a draft)
• Confirm the API key belongs to the same account that created the persona
• Use client.personas.list() to see which personas your key can access

Chat & Session Issues

NPC responses are slow (3–10 seconds)

This is expected — each message involves LLM inference (evaluation, summarization, and response generation). To improve perceived speed:

• Use the streaming endpoint (send_message_stream) to display text as it generates
• Use faster models for evaluation/summarization (e.g., gpt-4o-mini) via per-step model overrides
• Show a typing animation or loading indicator while waiting

Session not found (404) after restarting

Sessions are identified by user_session_id. If you lose this ID, the session cannot be recovered.

• Persist user_session_id in your game's save data or local storage
• Use get_session() to check if a session exists before sending messages
• If the session is gone, call init_session() to start a new one

NPC is stuck in a state / not transitioning

The AI evaluates transition conditions each turn. If no condition is met, the NPC stays in the current state.

• Check your transition conditions — are they too specific or contradictory?
• Use the chat preview to test different conversation paths
• Check the current_state field in each response to track where the NPC is
• Ensure you have a redirect transition as a fallback for off-topic messages

NPC breaks character

The NPC responds out of character or ignores its persona identity.

• Strengthen the persona_identity_prompt with explicit personality traits and speech patterns
• Add specific state prompt_instruction text reinforcing behavior for each state
• Test with adversarial messages to find where the character breaks

Rate Limiting

429 Too Many Requests

You've exceeded the rate limit for your endpoint category.

• SDK Chat: 30 requests/min per API key
• SDK General: 60 requests/min per API key
• Check the Retry-After header for when to retry
• The SDKs automatically retry with exponential backoff (up to 3 retries)
• If you consistently hit limits, queue messages client-side and throttle sends

SDK-Specific Issues

Unity: Streaming doesn't work on WebGL

WebGL builds use UnityWebRequest which does not support Server-Sent Events. Use the non-streaming SendMessageAsync endpoint for WebGL builds.

Unity: Coroutine streaming is not progressive

The coroutine version of SendMessageStream buffers the entire response before firing events due to Unity coroutine limitations. For true progressive streaming, use SendMessageStreamAsync (requires Unity 2023+).

Python: Connection timeout on long responses

Complex NPCs with many states may take longer to respond. Increase the client timeout:

client = FoilEngineClient(
    api_key="pk_live_...",
    llm_api_key="sk-...",
    timeout=60.0,  # Increase from default 30s
)

Still Stuck?

If none of the above resolves your issue:

• Enable debug=True (Python) or debug: true (TypeScript/Unity) to log all requests and responses
• Check the error response body — it includes a descriptive message
• Open an issue at GitHub