Troubleshooting
Find the message you see, or the behavior you notice, and follow the fix. Messages are quoted as the Peki dashboard, the website chat, Telegram or the API shows them. Where an API call returns an error, the HTTP status code is listed too.
How API errors look
API errors come back as JSON with a statusCode and a message. Credit errors also carry a code (credits_exhausted or plan_required) and file errors carry a file code such as file_size. Validation errors (400) add issues or errors that name the field. Read the message: it usually says exactly what to change.
Signing in
| Symptom | Cause | Fix |
|---|---|---|
| "This link is invalid or has expired." | The sign-in link was already used, or more than 15 minutes passed. (API: 401 "Sign-in link is invalid or expired") | Click Back to sign in and request a new link. Open it in the same browser if you can. |
"Too many sign-in links requested, try again later" (429) | More than 5 links for this email, or 20 from your network, in an hour. | Wait for the hour to pass, or sign in with Google. |
| No sign-in email arrives | Typo in the address, spam filtering, or a company mail filter. | Check spam, use Use another email to correct the address, or sign in with Google. |
"Email sign-in is not available yet. Continue with Google." (503) | Email sign-in is turned off. | Use the Google button. |
"Use the email sign-in link for this address" (409) | Google couldn't confirm it owns this email address. | Sign in with the email link instead. |
"This email is linked to a different Google account" (409) | Your Peki account is tied to another Google account with the same email. | Sign in with the original Google account, or with the email link. |
| You see a "Thanks" page instead of the Peki dashboard | Early access: you're on the waiting list. | Wait for our email, then sign in with the same account. Ask a teammate to invite you to skip the wait. |
| You were invited but don't see the workspace | You signed in with a different email than the one invited. | Sign out and sign in with the invited address, or ask an admin to invite the email you use. |
| You're signed out unexpectedly | Your session ended after 30 days without use, or you signed out in this browser. | Sign in again. |
Roles and access
| Symptom | Cause | Fix |
|---|---|---|
| "Read only — editors can change this agent" | Your role is Viewer or Operator. | Ask an admin to change your role in Settings → Members. |
| "Only admins can change workspace settings." | Workspace settings need Admin or Owner. | Ask an admin or owner. |
"Requires editor role" or "Requires admin role" (403) | Your role, or your API key's access, is below what the action needs. | Use a member with the right role, or an API key with Read and write access. |
"Not a member of this workspace" (403) | You were removed, or the app is pointing at a workspace you don't belong to. | Reload Peki and pick a workspace from Switch. Ask an admin to invite you again if needed. |
| "Your role no longer allows this" | Your role changed while you were working. | Reload. Ask an admin if you need the old role back. |
| "Only owners can add owners", "Only owners can change owners", "Only owners can remove owners" | Owner changes need an owner. | Ask an owner. |
| "A workspace needs at least one owner" | You tried to remove or demote the last owner. | Make someone else an owner first. |
| "Already a member or invited" | That email is already in the workspace's member list. | Change their role instead of inviting again. |
Credits and plans
| Symptom | Cause | Fix |
|---|---|---|
"You are out of credits." (402, code: credits_exhausted) | The workspace balance is 0 or less. The Copilot, tests, automations and new Knowledge stop. | Open Settings → Plan & credits and contact us to add credits. Nothing you built is lost. |
"Publishing needs a package." (402, code: plan_required) | The workspace is on the free plan. The Publish button shows a lock. | Packages are coming soon. Contact us from Settings → Plan & credits to go live now. |
| The Copilot stops in the middle of a build | The turn would have used up the remaining credits, so it stopped before the next model call. | Add credits, then click Continue. |
| "Paused: the workspace is out of credits. Add credits in Settings → Plan & credits, then resume." | An automation found no credits left. | Add credits, then resume the automation. |
| The credits line in the sidebar looks low | The balance is under 50 credits. | Plan ahead: contact us before it reaches zero. |
Building and publishing
| Symptom | Cause | Fix |
|---|---|---|
| "Every block needs a title and text before the draft saves." | A prompt block is empty or has no title. | Fill in or delete the incomplete block. |
| "Fix the incomplete blocks before testing." | Same as above, in the Test panel. | Same fix. |
"An agent needs at least one instruction block" (400) | You tried to delete the last block. | Keep at least one block. |
| "The draft changed (Copilot or a teammate); reloaded." | Someone else, or the Copilot, saved the draft while you were editing. | Check the reloaded draft and redo your change if needed. |
"The draft changed while editing; try again" (409) | Two saves happened at once. | Try again. |
"Draft was already published" or "Agent changed during publish" (409) | Someone published or changed the agent at the same moment. | Reload Instructions and publish again if there are still changes. |
| "Name is not published yet: publish it before this agent." | A team member agent has never been published. | Publish that agent first, then this one. |
| "This agent was deleted: remove it before publishing." | A team member agent no longer exists. | Remove it under Instructions → Team. |
| "Describe what it is good at before publishing." | A team member has no description. | Fill in What it is good at for that member. |
| "An agent can't be on its own team." | You added the agent to its own team. | Pick a different agent. |
| Customers still see the old behavior | Your changes are in the draft. | Click Publish. Channel settings, Knowledge and variables are the only things that apply without publishing. |
"This agent has no published version yet" or "Publish the agent first" (409) | Something needs the live version, such as an automation or a real run. | Publish the agent. |
| "Real runs use the published agent; dry-run the draft" | You tried a real run against the draft. | Use a dry run to try the draft, or publish first. |
Testing
| Symptom | Cause | Fix |
|---|---|---|
| "The agent couldn't answer. Check the model and try again." | The model failed and there's no fallback reply. | Check Instructions → Model. Add a fallback model, and a Fallback reply. |
| "Fallback reply — the model couldn't answer." | Both models failed or timed out, so the fallback reply was sent. | Try again. If it repeats, pick another primary model, or make the agent call fewer tools per reply. |
"Only editors can test" (403) | Testing needs the Editor role. | Ask an admin for the Editor role. |
| A test reply ignores a condition like "customer has tag vip" | The test customer doesn't have the tag. | Set the tag in the Test panel. Real customers get tags in the Inbox. |
| A business-hours block never applies | Business hours aren't set, so such a block is never sent. | Set them in Settings → Business hours. |
Copilot
| Symptom | Cause | Fix |
|---|---|---|
| "The Copilot is still working on this chat. Wait for it to finish, or press Stop." | A turn is still running. | Wait, or click Stop, then send your message. |
| "That card was answered just now, so your message was not sent. Send it again once the Copilot is done." | You answered a card and sent a message at the same moment. | Send the message again when the Copilot is done. |
| "Answer the card first (or press Stop), then send the files." | The Copilot is waiting on a card. | Answer the card or click Stop. |
| "The Copilot stopped with an error." | A model or tool error ended the turn. | Click Continue. If it repeats, switch the Copilot model. |
| "Tool call limit (40) reached for this turn" | The request needed more than 40 steps in one turn. | Click Continue, or split the request into smaller ones. |
| "The turn took too long and was stopped" | A turn is limited to 20 minutes. | Click Continue. |
| "The Copilot stopped unexpectedly; send your message again" | The turn was interrupted. | Send your message again. |
| "The person behind this chat is no longer a member of this workspace" | The member who started this Copilot chat was removed. | A current editor continues in their own session. |
| "A key (····1234) was taken out of your message…" | You pasted something that looks like a key. Peki removed it before the model saw it. | If the message says it saved the key, you're done. Otherwise use the key card, name the key's one site, or ask an editor. |
| "This turn changed nothing; there is nothing to undo" or "This turn has not ended yet" | Undo is only for finished turns that changed something. | Wait for the turn to end, or undo a different turn. |
| "Areas changed after this turn…" with Undo anyway | You or a teammate changed the same things after this turn. | Read the list. Undo anyway loses those later changes too. |
| "Turn undone. Kept because live agents use them: …" | Some changes are used by the published version, so Undo kept them. | Publish or change those parts by hand if you still want them gone. |
"Undo needs the editor role" or "Saving a key needs the editor role" (403) | Your role is below Editor. | Ask an admin for the Editor role. |
| "This card names no section; ask the Copilot again" or "This key card has no valid sites; ask the Copilot again" | The card is incomplete. | Ask the Copilot to show the card again. |
| "Choose a model from the Copilot's list" | The chosen model isn't offered. | Pick one from the model picker above the message box. |
Tools and keys
| Symptom | Cause | Fix |
|---|---|---|
| "This API key may only be sent to site" | The tool's URL is on a site the key isn't allowed for. | Fix the tool's URL, or add the site to the key in Settings → Secrets. |
| "This API key has no allowed sites yet: an admin can set them in Settings → Secrets" | The key has no site list. | An admin adds the site in Settings → Secrets. |
| "This API key is not assigned to an agent yet…" | The key was saved before keys belonged to agents; it's under Unassigned. | An admin uses Assign to… in Settings → Secrets. |
| "This API key belongs to another agent" | Each key belongs to one agent. | Save the key again for this agent. |
| "The API key for this tool was deleted" | The secret was removed. | Choose another key for the tool, or add a new one. |
| "This key is a webhook signing key…" | A signing secret only checks incoming signatures; it's never sent. | Use a normal key for the tool. |
"A key with this name already exists" (409) | Key names are unique. | Pick another name or update the existing key. |
"A key is 4 to 4000 characters" (400) | The value is too short or too long. | Paste the full key. |
A tool returns HTTP 401 or HTTP 403 | The API rejected the key. | Check the key, its auth type (Bearer or header name) and its permissions with the API provider. |
A tool returns HTTP 404 | Wrong URL or input. | Check the URL and inputs in the tool editor; try it with real input. |
A tool calling localhost or a private IP fails | Private network addresses are blocked. | Use a public address for your API. |
| A tool's answer seems cut off | Responses are cut at the tool's response size (default 4,000 characters). | Raise it (up to 20,000) or keep fewer response fields. |
Functions
| Symptom | Cause | Fix |
|---|---|---|
| "host is not in this function's hosts (…): add it to the function's hosts" | The Function tried to reach a site that isn't in its list. | Add the site to the Function's allowed sites. |
| "The secret name is not in this function's secrets" | The code names a key the Function doesn't list. | Add the key to the Function's keys. |
| "The secret name may only be sent to …" or "…is only sent over https" | The key isn't allowed for that URL, or the URL isn't https. | Use an allowed https URL, or add the site to the key. |
| "Timed out after 5000 ms" | The run took longer than its timeout. | Raise the timeout (up to 10 seconds), or make fewer or faster calls. |
| "Memory limit exceeded…" or "CPU limit exceeded…" | The run used too much memory or CPU. | Process less data at once; keep only the fields you need. |
| "Result is … KB; the limit is 16 KB" | The returned value is too big. | Return only what the agent needs. |
| "Output exceeded 64 KB; the function was stopped" | Too much printed output. | Log less. |
| "A function run may make at most 20 requests" | Too many web requests in one run. | Batch requests or split the work. |
| "The table key can't be read by the agent (Records → Table settings → Agent access)" | ctx.records tried to read a table without read access. | Turn on read in that table's Agent access, if that's safe for its data. |
| "The function runner is busy…" or "…is unreachable" | Functions are temporarily unavailable. | Try again shortly. |
| "A Function named name already exists…" | Names are unique per agent. | Pick another name, or replace the existing one. |
| A run is refused for the agent | The agent hit 60 runs per minute, 3,600 seconds per day, or 4 runs at once. | Spread automation schedules out, or make runs shorter. |
Knowledge
| Symptom | Cause | Fix |
|---|---|---|
| "This source could not be read." | A scanned PDF with no text, an empty or script-only page, or a site that blocks readers. | Upload a PDF with selectable text, paste the text, or add a different page. |
| "Use a PDF, TXT, Markdown or CSV file" | Unsupported file type, such as DOCX. | Save it as PDF or paste the text. |
| Upload rejected for size | Files are limited to 10 MB. | Split the file. |
| The agent doesn't use a source | The question is too far from the content, or the source failed. | Check the source status. Add a source that answers that question in plain words. |
| Adding a source fails with "You are out of credits." | Reading sources uses credits. | Add credits. |
Website chat
| Symptom | Cause | Fix |
|---|---|---|
| The chat doesn't appear on your site | The widget is off, the snippet is missing, or your site isn't allowed. | Turn on Show the chat on your website, click Save, paste the Embed code before </body>, and add your exact site address to Allowed websites. |
| "This chat is not available right now." | The widget is turned off or the key in the snippet is wrong. (API: 404 "This chat is not available") | Turn the widget on, or copy the Embed code again. |
The browser console shows 403 "This website may not use this chat" | The page's address isn't in Allowed websites. | Add it exactly, with https:// and the right subdomain, for example both https://shop.example.com and https://www.shop.example.com if you use both. |
| "This assistant is not available yet" | The agent has never been published. | Publish the agent. |
| "You are sending messages too fast." | More than 20 messages a minute from one visitor. | Wait a moment. |
| "This chat is very busy right now. Please try again in a minute." | More than 120 messages a minute on this widget. | Wait a minute. |
| "Too many messages from this network…" or "Too many new chats from this network…" | Many visitors behind one network (an office, a test script). | Wait for the hour to pass. |
| "This assistant is very busy right now. Please try again later." | The workspace reached its 2,000 live replies for the day. | Replies resume after midnight UTC. Contact us if you need more. |
| "Could not send. Please try again." | A network or server error. | Try again. |
| Try it conversations show up in Analytics | They are real conversations with the published agent, as "Widget tester". | Expected. Use the Test panel for conversations that aren't counted. |
Telegram
| Symptom | Cause | Fix |
|---|---|---|
| "That does not look like a bot token. Copy it again from @BotFather." | The pasted text isn't a bot token. | Copy the full token from @BotFather. |
| "Telegram didn't accept this token… Copy it again from @BotFather." | The token is wrong or was revoked. | Get the current token from @BotFather. |
| "This bot is connected to agent. Move it here?" | The bot belongs to another agent. | Click Move it here, or use another bot. |
| "This bot is also being used somewhere else (another server or app)…" | Another system is reading the same bot's messages. | Stop the other system. If it isn't yours, renew the token with @BotFather (/revoke) and connect the new one. |
| "This bot changed hands just now; try again" or "This bot was just connected to another agent; try again" | Two connections happened at once. | Try again. |
| "Connect a bot first" or "Connect Telegram first" | The action needs a connected bot. | Connect the bot in Channels. |
| "Not a chat of this agent's bot: … Send the bot a message from that chat first" | An automation names a Telegram chat the bot hasn't seen. | Send the bot /start from that chat, then save again. |
| The bot replies "This assistant is not available yet." | The agent isn't published. | Publish the agent. |
| The bot replies "We are very busy right now. Please write again in a little while." | The daily live reply limit was reached. | Replies resume after midnight UTC. |
| The bot ignores messages | Answer messages to this bot is off, or the customer sent more than 20 messages in a minute. | Turn it on in Channels; ask the customer to wait a moment. |
| "I can't open this kind of file yet…" | Voice notes, stickers and similar aren't supported. | Send a photo, PDF or text file, or type the message. |
| "That file is too big: files can be up to 10 MB." | The file is over 10 MB. | Send a smaller file. |
| "This conversation already has 30 files. Send /new to start a new one." | The 30-file limit per conversation. | Send /new. |
| "I couldn't download that file. Please send it again." | Telegram failed to hand out the file three times. | Send it again. |
Inbox
| Symptom | Cause | Fix |
|---|---|---|
"Take over to reply yourself" / "Take over the conversation to reply" (409) | You must take over before replying. | Click Take over. |
"Take over the conversation to send files" (409) | Same, for attachments. | Click Take over. |
"Name has already taken over" (409) | A teammate took it first. | Coordinate with them, or wait until they hand it back. |
"Nobody has taken over this conversation" (409) | You tried to hand back a conversation nobody took over. | Nothing to do. |
| A handed-off conversation isn't in Needs you | A teammate took it (see Taken over) or it was resolved. | Check Taken over and All. |
Files
These codes come back from every channel and the API.
| Code | Message | Fix |
|---|---|---|
file_type | "Send a photo (JPEG, PNG, WebP, GIF), a PDF or a text file (TXT, MD, CSV)." | Use a supported type. The type is checked from the file itself, so renaming doesn't help. SVG and HTML are never accepted. |
file_size | "Files can be up to 10 MB." | Send a smaller file. |
file_count | "Up to 5 files per message." | Send the rest in another message. |
conversation_full | "This conversation has reached its 30-file limit. Start a new conversation to send more." | Start a new conversation. |
file_rate | "Too many files at once. Please try again later." | Wait, then try again. |
file_taken | "This file was already sent. Please attach it again." | Attach the file again. |
file_missing | "This file is no longer available. Please attach it again." | Attach it again. Uploads not sent within 24 hours are deleted. |
| — | The agent says it can't see the photo | The model doesn't read images. Pick a model marked Reads images as the primary model. |
| — | The agent can't read a PDF | The PDF is a scan with no text layer. Ask for a text PDF or a photo. |
Records
| Symptom | Cause | Fix |
|---|---|---|
| "A record holds at most 32 KB; shorten long fields" | The record is too large. | Shorten long text fields. |
| "An agent has at most 20 tables" | The table limit. | Combine tables or remove unused ones. |
| "This is the title field: choose another title to delete it." | Every table needs a title field. | Pick another title field first. |
| "The CSV file is empty", "A CSV file can have at most 5000 rows", "A CSV file can be at most 2 MB" | Import limits. | Split the file. |
| "Not saved: a matching record exists now; this request was to add a new one" | Another save with the same match-on values happened first. | Open the existing record and update it. |
| The agent can't look up records | The table's Agent access doesn't allow read. Tables of people keep it off on purpose. | Turn on read only for tables of your own items, never for tables of people. |
| A field you edited by hand didn't change after the fill | By design, the records fill never overwrites a field changed by hand. | Edit it yourself. |
Approvals
| Symptom | Cause | Fix |
|---|---|---|
| "Expired: nobody decided within 24 hours." | Requests expire after 24 hours. | Ask the customer again, or turn on Telegram notices for new requests. |
| "This action no longer exists in the agent, so approving it would fail. Reject it instead." | The tool or Function was removed after the request. | Reject it. |
| "Action changed since this was requested: review the values and approve again" | The action changed after the request. | Review the values and approve again. |
"Your role does not allow approving this" (403) | Your role is below what the action needs. | Ask an editor or admin. |
| "Approved by … but it failed" | The action ran and the target system returned an error. | Open the result, fix the cause (key, URL, values) and ask the customer to try again. |
Automations
| Symptom | Cause | Fix |
|---|---|---|
| "Paused automatically: …" with a daily limit | It hit Runs per day or Model cost per day. | Click Raise limit, or make it run less often, then resume. |
| "Paused after 5 failed runs in a row. Last error: …" | Five failures in a row. | Read the last error on the Runs tab, fix it, dry-run, then resume. |
| Paused because a tool started writing | A tool it uses now changes data, so its writes need approval again. | Review and approve the writes, then resume. |
| "Skipped — previous run still going" | The previous run hadn't finished. | Make the run shorter, or schedule it less often. |
| "Held — quiet hours" | Messages are held during quiet hours. | Expected. Change Quiet hours if needed. |
"A run of this automation is still in progress; wait for it to finish" (409) | You started Run once during a run. | Wait, then try again. |
"Saved, but its schedule could not be updated right now; it is repaired automatically within 10 minutes" (503) | The schedule couldn't be updated at that moment. | Nothing to do; it fixes itself within 10 minutes. |
"The automation changed while you were saving (it may have been paused automatically); reload and try again" (409) | It changed during your save. | Reload and save again. |
| "Publish the agent first: an automation that is on runs the published version." | The agent isn't published. | Publish the agent. |
"What needs the editor role (the role that may publish this agent); you are …" (403) | Creating automations and approving their writes need the role that may publish. | Ask an editor. |
| "Not sent: sending took longer than 30 s" | Telegram didn't accept the message in time. | It's recorded on the run; the next run tries again. |
| "Telegram is not connected to this agent" | Delivery needs the agent's bot. | Connect Telegram in Channels. |
"Only webhook automations have a URL" (400) | You asked for a URL on a scheduled or event automation. | Change its trigger to a webhook. |
"The sample payload is larger than 256 KB" (400) | The Run once sample is too big. | Use a smaller sample. |
Webhook calls from other systems
| Response | Cause | Fix |
|---|---|---|
404 {"error":"Not found"} | The URL is wrong, was renewed or revoked, or the automation is paused or off. | Copy the current URL from the automation. Renew stops the old URL at once. |
401 "Invalid signature" | The signature check failed. | Save the sending system's signing secret again; make sure the provider (Stripe, Shopify, GitHub or HMAC-SHA256) matches. |
401 "Invalid signature", and Requests shows "The signing key name is missing" | The signing secret was deleted. | Save the signing secret again under the same name. |
413 "Payload too large" | The body is over 256 KB. | Send less data, or only an id the Function can look up. |
429 "Too many requests" | More than 60 calls a minute to this URL, 600 a minute from one IP, or 100 runs waiting. | Slow down the sender; it will usually retry. |
200 {"duplicate":true} | The same delivery already arrived in the last 24 hours, so it doesn't run twice. | Expected: senders retry, and Peki runs each delivery once. |
503 {"error":"Try again shortly"} | The run couldn't be queued at that moment. | The sender's retry gets through; nothing is lost. |
202 {"accepted":true,"id":"..."} | Success: the run was queued. | Check the Runs tab for the result. |
API
| Symptom | Cause | Fix |
|---|---|---|
401 "Sign in required" | No Authorization: Bearer … header. | Send your API key as a Bearer token. |
401 "Invalid API key" | The key is wrong or revoked. | Create a new key in Settings → API keys. |
403 "Requires editor role" | A Read only key tried to write, such as sending a message. | Use a key with Read and write access. |
403 "Not available to API keys" | That endpoint is for signed-in people only, such as managing members or keys. | Do it in Peki. |
403 "API key belongs to another workspace" | You sent an x-workspace-id header for a different workspace. | Drop the header; an API key already knows its workspace. |
400 "Invalid body" with issues | A field is missing or invalid. | Read issues: each names the field and the problem. |
400 "Write a message or attach a file" | The message is empty. | Send text or attachments. |
409 "Only sessions started through the API take messages here" | You sent to a website chat, Telegram or test conversation. | Start a session with the Sessions API and send to that. |
409 "This agent has no published version yet" | The agent isn't live. | Publish the agent. |
404 "Session not found" or "Agent not found" | Wrong id, or it belongs to another workspace. | Check the id. |
503 "Could not accept the message right now. Please try again." | A temporary problem. | Retry with a short delay. |
A streamed reply ends with {"type":"done","timedOut":true} | The stream closes after 120 seconds. | Read the reply from the session's messages afterwards. |
429 "This assistant is very busy right now. Please try again later." | The workspace's daily live reply limit. | Retry after midnight UTC. |
Usage reports
| Symptom | Cause | Fix |
|---|---|---|
| "At most 92 days at a time" or "At most 366 days at a time" | The date range is too long. | Pick a shorter range. |
"from must be on or before to" | Dates are swapped. | Swap them. |
| Older agent replies show no cost | Customer reply cost is recorded from October 2026. | Expected. |
Still stuck?
Check the Limits for the exact numbers, and the FAQ. The Why? link under a reply in the Inbox shows which blocks, tools, skills and Knowledge a reply used, which explains most surprising answers.