| title | Pinata Agents API error reference |
|---|---|
| sidebarTitle | Errors |
| description | Look up any Pinata Agents API error code, understand what it means, and follow the steps required to resolve the issue and unblock your agent. |
| icon | circle-exclamation |
Every API error comes back as JSON with a single error field and an HTTP status code:
{ "error": "Validation failed: skills exceeds maximum of 10" }This page maps the codes you'll actually see in the wild to a cause and a fix. For step-by-step debugging, see Troubleshooting.
The request shape or content is invalid.
| When you'll see it | Likely cause | Fix |
|---|---|---|
POST /v0/agents |
name missing, too long, or contains banned characters |
Trim or rename. Max 100 chars. |
POST /v0/secrets |
name or value empty |
Provide both |
POST /v0/agents/.../skills |
More than 10 skills attached | Detach skills first |
POST /v0/agents/.../console/exec |
Empty command |
Provide the command string |
POST /v0/agents/.../snapshots/sync |
Storage not configured for this workspace | Pinata storage isn't provisioned - contact support |
POST /v0/agents/.../config/validate |
config field isn't valid JSON |
Fix syntax |
POST /v0/agents/.../domains |
Both subdomain and customDomain provided, banned name, or limit reached |
Pick one. Avoid names containing "pinata". Max 5 domains. |
POST /v0/agents/.../snapshots/reset |
snapshotCid missing or malformed |
Use a CID from the snapshot list |
POST /v0/agents/.../channels/{channel} |
Token missing on initial setup, or unsupported channel name | Provide botToken (and appToken for Slack) |
POST /v0/agents/.../files/upload |
filename empty or contentBase64 malformed |
Sanitize filename, base64-encode without the data URL prefix |
No credential, or the credential was rejected before reaching authorization.
| Cause | Fix |
|---|---|
Missing Authorization header |
Add Authorization: Bearer <token> |
| Pinata JWT expired or revoked | Generate a new key in Account → API Keys |
| Gateway token rotated | Copy the current value from Danger → Agent → Gateway Token |
| Token from a different workspace | Switch workspaces in Account → Workspaces or use a key from the right workspace |
Authenticated, but the action isn't allowed.
| Cause | Fix |
|---|---|
Agent limit reached on POST /v0/agents |
Upgrade your plan or delete an unused agent |
| Free plan trying to use a paid feature (channels, custom domains) | Upgrade plan |
| Workspace permission denied | Ask the workspace admin for access |
404 returned where you expected 403 (Issues API on non-internal accounts) |
Issues is closed beta to @pinata.cloud only |
The resource doesn't exist (or you're not allowed to know it exists).
| Cause | Fix |
|---|---|
Wrong agentId |
Check the ID from the Danger page or GET /v0/agents |
snapshotCid not in this agent's history |
Use one from GET /v0/agents/{agentId}/snapshots |
| Skill CID/slug not installed in your library | Install via Skills Library or POST /v0/clawhub/{slug}/install |
| Template slug/ID doesn't exist or was archived | List GET /v0/templates |
| Custom domain ID not on this agent | List GET /v0/agents/{agentId}/domains |
| Issues endpoint hit by a non-internal account | Closed beta - returns 404 by design |
Resource state is incompatible with the request.
| Cause | Fix |
|---|---|
Duplicate secret name on POST /v0/secrets |
Use a different name or update the existing one |
Two credentials for the same provider attached (e.g. OPENAI_API_KEY + Codex subscription) |
Detach one |
| Custom domain already registered (verified) | Pick a different name or delete the existing registration |
| Subdomain collides with another tenant | Generate a new one or pick a different name |
| Trying to delete a secret still attached to an agent | Detach from agents first |
| Skill version conflict during update | Resolve via POST /v0/agents/{agentId}/skills/{skillId}/update |
File upload exceeded the per-request limit.
| Cause | Fix |
|---|---|
POST /v0/agents/{agentId}/files/upload body too big |
Chunk the upload, or push the file via git, or stream it from inside the container |
Something blew up on the server. The error field usually has the underlying message.
Common variants:
| Message hint | Cause | Fix |
|---|---|---|
Gateway failed to start after agent create |
Provisioning succeeded but the gateway crashed | Wait 30s and retry, or check Logs |
Sync failed |
Workspace snapshot upload to Pinata IPFS failed | Retry; if persistent, check Pinata status |
CLI error on GET /v0/agents/{agentId}/devices |
Underlying engine CLI returned non-zero | Check Logs for engine errors; restart gateway |
Reset failed |
Git reset to the snapshot commit failed | The commit hash may be missing - try a different snapshot |
Configuration failed on channel configure |
The engine rejected the channel config | Validate token format (e.g. Slack xoxb- / xapp-) |
Execution failed on console exec |
Command shell terminated unexpectedly | Inspect the command; if hung, restart gateway |
A dependency the server needs is down.
| Cause | Fix |
|---|---|
POST /v0/secrets returns 503 with "Secrets not configured" |
Server-side encryption key not provisioned. Contact support. |
| Snapshot/IPFS backend unreachable | Retry; check Pinata status page |
The container takes ~30 seconds to provision. A 500 with the agent body in the response means provisioning succeeded but the gateway didn't start cleanly - the agent will appear in your list and you can restart it.
Re-grab the URL with Copy with Token on the Files tab. The gateway token may have been rotated.
This usually means the engine CLI inside the container failed. Restart the gateway; if it keeps failing, check the Logs filtered to cron/runner.
The engine could not write the channel config or restart. Almost always a malformed token or a channel that's already enabled. Re-check the token, then Reconfigure.
Your _pinata-verify.<domain> TXT record isn't visible. Confirm with dig TXT _pinata-verify.<domain> +short and wait for propagation.
Issues is closed beta and restricted to @pinata.cloud accounts today.
Errors documented in the API spec, grouped by where they appear. Use this as a starting point when you're trying to interpret an error response — the exact string returned by the API is the source of truth.
| Response | Where it appears | What it means |
|---|---|---|
Missing userId |
Several JWT-protected endpoints | Pinata JWT couldn't be resolved to a user — regenerate the key |
Agent limit reached |
POST /v0/agents (403) |
Workspace at its agent quota — upgrade or delete an unused agent |
Storage not configured |
POST /v0/agents/{agentId}/snapshots/sync (400) |
Workspace has no backing storage; contact support |
Sync failed |
Snapshot sync (500) |
IPFS pin or workspace serialization failed — retry |
Snapshot not found |
POST /v0/agents/{agentId}/snapshots/reset (404) |
Snapshot CID isn't in this agent's history |
Invalid snapshot CID |
Snapshot reset (400) |
The provided CID didn't parse |
Unsupported channel |
DELETE /v0/agents/{agentId}/channels/{channel} (400) |
Channel must be telegram / slack / discord / whatsapp |
Configuration failed |
Channel configure (500) |
Engine rejected the token/config |
Removal failed |
Channel delete (500) |
Engine failed to remove and restart |
Invalid command |
Console exec (400) |
command field empty or invalid cwd |
Execution failed |
Console exec (500) |
Shell exited unexpectedly |
Invalid JSON / invalid config |
Config validate / write (400) |
The config field isn't valid for this engine |
Validation command failed |
POST /v0/agents/{agentId}/config/validate (500) |
Engine validator returned non-zero |
Failed to read config |
GET /v0/agents/{agentId}/config (500) |
Couldn't read runtime config |
Failed to write config |
PUT /v0/agents/{agentId}/config (500) |
Couldn't write runtime config |
Invalid version |
POST /v0/agents/{agentId}/restart (400) |
Requested engine version doesn't exist |
Restart failed |
Restart (500) |
Gateway didn't come back up — check Logs |
Script launch failed |
POST /v0/agents/{agentId}/scripts/retry (500) |
Build or start couldn't be launched |
File too large |
POST /v0/agents/{agentId}/files/upload (413) |
Body over the upload limit — chunk or push via git |
CLI error |
Several engine-backed endpoints (500) |
Underlying engine CLI returned non-zero — check Logs |
Token generation failed |
POST /v0/agents/{agentId}/platform/token (500) |
Platform JWT couldn't be minted — rotate gateway token |
Secrets not configured |
POST /v0/secrets (503) |
Server-side encryption key not provisioned — contact support |
Duplicate secret name |
POST /v0/secrets (409) |
Secret name is already taken |
Conflicting secrets |
POST /v0/agents/{agentId}/secrets (409) |
Attaching two creds for the same provider (e.g. API key + subscription) |
Invalid parameters |
Tasks create (400) |
One of name, schedule, or payload is missing or malformed |
Failed to create cron job |
Tasks create (500) |
Engine rejected the cron config |
Failed to list cron jobs |
Tasks list (500) |
Engine CLI failed |
- Concepts - terminology and how the pieces fit
- Troubleshooting - step-by-step debugging by symptom
- HTTP API - auth and base URLs
- Manifest reference - manifest schema details