Troubleshooting

You can solve most problems by asking your agent. When you need Flovia, contact Flovia (opens in new tab) or ask your agent to send feedback.

Flovia’s tools do not appear

• Restart your agent after adding Flovia, or reconnect the flovia MCP server.
• Check that the key is set where the setup reads it. For Codex, that is the FLOVIA_KEY environment variable.
• If Flovia rejects the key, check it in Console (opens in new tab) and set it again.
• If Flovia does not respond, wait and try again, or send feedback.

Flovia refuses your key or sign-in

• HTTP 401 with formal_registration_required: Test access has ended. API keys issued during the test no longer work. Complete formal registration from your invitation email, then open https://console.flovia.dev/auth/ (opens in new tab) to connect your app again. Test-period history and stored answers do not carry over to your new account.
• HTTP 401 with unauthorized: Flovia did not accept the key, or none was sent. Check your key in Console (opens in new tab) and send it in the Authorization header as Bearer followed by the key. If you connected with OAuth, connect again from Quick Install in Console.
• HTTP 403 with formal_registration_required: you connected with OAuth, and test access for that account has ended. Complete formal registration from your invitation email, then connect again from https://console.flovia.dev/auth/ (opens in new tab).
• Check your connection shows the same answers as a table.

A limit is reached

• When a free window reaches 100%, free lookups pause until it resets. Ask your agent when it resets.
• Adding to your purchased balance is paused for now. Wait for the window to reset, or ask your agent to send Flovia feedback.
• If a data source is busy or rate limited, try again later. When the reply gives a wait time, wait that long first.
• Free and paid use explains the limits.

The result is unknown, or your agent stopped

• If a reply was lost or Flovia cannot tell whether a call ran, send the same request again with the same operation ID. It is never charged twice. Never start a new operation to recover an answer.
• If your agent stops midway, say “Continue from today’s Flovia lookups”. Finished lookups are reopened rather than fetched again.

Reopen an earlier answer

• Save each answer on your side as soon as it arrives.
• For data lookups other than Nansen, for about 15 minutes after a lookup completes, only you can reopen its answer with flovia_lookup and its lookup ID, at no cost. About 15 minutes is a guide, not a promise: if Flovia could not keep the copy, or the copy is not visible yet, you get only the record even within those minutes.
• For these data lookups, after about 15 minutes, flovia_lookup shows only the lookup’s record, such as its ID and status, and the answer does not come back. Do not start a new lookup automatically; ask again only if you want fresh data.
• Nansen is different: flovia_lookup returns Nansen’s stored answer from the time of the lookup.
• For OpenAI text generation, the ID is openai: followed by the generation ID. Its answer is also kept for about 15 minutes, for you only. If the OpenAI answer has expired, flovia_lookup returns ok: false with explanation.code: replay_response_unavailable and generation_code: answer_expired, without status or stored_answer. The SDK reports this as FloviaError. Do not generate again automatically.
• After formal registration you have a new account. Lookups made with a test-period key, and their stored answers, are not visible from it.
• First lookup and its reply shows a reopened answer and what to save.

An answer looks wrong

Ask your agent to send your feedback to Flovia in your own words. A lookup deducts at most its usual cost, and less if the answer is wrong. Your agent can also tell you what happened to feedback you sent.

Your key is lost or leaked

Contact Flovia (opens in new tab). Flovia revokes the old key and issues a new one. Never paste a key into a conversation or a public repository.

Refunds and payments

• Any unused purchased balance can be refunded on request. Ask your agent to “Send Flovia feedback asking for a refund”. If you stopped sharing, ask within 30 days, because feedback is deleted after 30 days. If Flovia suspends or terminates your account for a Terms violation, the unused purchased balance is not refunded unless the law requires it (Terms §3 (opens in new tab)).
• If a payment could not be confirmed, your agent resends the same payment instead of making a new one. If it still cannot be confirmed, Flovia checks the blockchain within 3 business days (Japan business days) and either adds the amount to your purchased balance or tells you why not.

Find out what changed

Flovia is in alpha. To see what changed, ask your agent “What changed in Flovia recently?” (recent_updates in flovia_status).