Errors
MCP errors
Requests with an invalid key are refused before any MCP processing takes place. All other errors are returned as tool results marked as errors, so your assistant can read them and explain how to resolve the problem.
Before the connection
These are HTTP responses. Your client reports them as a failed connection.
| Status | When |
|---|---|
401 | No key was sent, or the value is not shaped like a GunSpec key. |
404 | The request was not sent to the endpoint path. |
In a tool result
The reason returned by the API, its meaning and the recommended action. For a refusal, the model receives the API's message. For a server-side failure, the model receives a short message with a request ID instead of internal details.
| Reason | Meaning | What to do | Model sees |
|---|---|---|---|
KEY_INVALID 401 | The API key is not one we issued, or it has been deleted. | Check the key for a typo, or create a new one in your account. | The refusal |
KEY_DISABLED 401 | The key was switched off by the account that owns it. | Re-enable it in your account, or use another key. | The refusal |
KEY_EXPIRED 401 | The key has passed its expiry date. | Create a new key in your account. | The refusal |
ACCOUNT_SUSPENDED 403 | The account behind this credential has been suspended. | Contact support. Rotating the key will not help. | The refusal |
PLAN_REQUIRED 403 | The credential is valid and its plan is below what this endpoint needs. details.requiredTier names the plan. | Upgrade the plan. A new key on the same plan will get the same answer. | The refusal |
PAGINATION_DEPTH_EXCEEDED 403 | The plan does not page this deep into a list. | Narrow the list with filters, or upgrade for deeper paging. | The refusal |
INVALID_PARAMETER 400 | A path, query or body field failed validation. details names each field and what was wrong with it. | Correct the named fields and send the request again. | The refusal |
RESOURCE_NOT_FOUND 404 | The path is right and no record has that id. | Check the id. The list and search endpoints return valid ones. | The refusal |
RATE_LIMITED 429 | Too many requests this minute for the plan. | Wait for Retry-After seconds, then retry. | The refusal |
DAILY_CAP_EXCEEDED 429 | The plan's daily request allowance is used up. It resets at midnight UTC. | Wait for the reset, or upgrade for a larger allowance. | The refusal |
MCP_DAILY_CAP_EXCEEDED 429 | The plan's daily allowance for calls through the MCP server is used up. It resets at midnight UTC; direct API requests still count against the plan's own allowance. | Wait for the reset, call the API directly, or upgrade for a larger MCP allowance. | The refusal |
PAGINATION_BURST 429 | Too many sequential pages in a short time. | Slow the walk down, or use a larger per_page. | The refusal |
INTERNAL_ERROR 500 | Something failed on our side. It has been logged against request_id. | Retry with backoff. Quote request_id if it persists. | A retry notice with a request id |
DEPENDENCY_UNAVAILABLE 503 | A service this endpoint depends on is temporarily unavailable. | Retry after a short wait. | A retry notice with a request id |
MAINTENANCE 503 | The API is paused for maintenance. | Wait for Retry-After seconds, then retry. | A retry notice with a request id |