> ## Documentation Index > Fetch the complete documentation index at: https://pinata-mintlify-5df45191.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Pinata Agents API error reference > 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. Every API error comes back as JSON with a single `error` field and an HTTP status code: ```json theme={null} { "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](/agents/troubleshooting). ## By HTTP status ### `400 Bad Request` 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 | ### `401 Unauthorized` No credential, or the credential was rejected before reaching authorization. | Cause | Fix | | -------------------------------- | ----------------------------------------------------------------------------------- | | Missing `Authorization` header | Add `Authorization: Bearer ` | | Pinata JWT expired or revoked | Generate a new key in [Account → API Keys](/account-management/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 | ### `403 Forbidden` 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 | ### `404 Not Found` 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 | ### `409 Conflict` 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` | ### `413 Payload Too Large` 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 | ### `500 Internal Server Error` 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 | ### `503 Service Unavailable` 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 | ## By symptom ### "I just created the agent and the chat shows offline" 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. ### "My push to the workspace returns auth errors" Re-grab the URL with **Copy with Token** on the Files tab. The gateway token may have been rotated. ### "Tasks return 500 from `GET /v0/agents/.../tasks`" This usually means the engine CLI inside the container failed. Restart the gateway; if it keeps failing, check the Logs filtered to `cron/runner`. ### "Channel configure returns 500" 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**. ### "Domain stuck `pending_ownership`" Your `_pinata-verify.` TXT record isn't visible. Confirm with `dig TXT _pinata-verify. +short` and wait for propagation. ### "Issues endpoints all return 404" Issues is closed beta and restricted to `@pinata.cloud` accounts today. ## Common error responses 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 | ## See also * [Concepts](/agents/concepts) - terminology and how the pieces fit * [Troubleshooting](/agents/troubleshooting) - step-by-step debugging by symptom * [HTTP API](/agents/api) - auth and base URLs * [Manifest reference](/agents/manifest) - manifest schema details