Troubleshooting
Resolve connection, permission, credit and recommendation errors.
Start with get_connection_status, then inspect the tool result's code, status and message. Some clients wrap server errors in an MCP tool error instead of displaying the underlying HTTP status. A successful OAuth connection does not by itself guarantee plan access or permission to spend.
Connection and permissions
| Code or symptom | What to do |
|---|---|
CONNECTION_EXPIRED | Reconnect and complete OAuth. The connection may have expired, been revoked or lost workspace membership. |
WORKSPACE_CONSENT_REQUIRED | Reconnect and approve current workspace access. A legacy product-only grant cannot use current workspace capabilities. |
SCOPE_MISMATCH | Use a product within the authorized scope, or reconnect to the correct workspace. |
PAID_PLAN_REQUIRED | Check the workspace's active plan, trial or eligible membership. A Credit pack alone does not enable MCP. Basic includes MCP. |
WORKSPACE_MEMBERSHIP_REQUIRED / WORKSPACE_ROLE_REQUIRED / WORKSPACE_VIEW_ONLY | Ask the owner or admin to check your membership and role. Viewers cannot perform paid or write actions. |
PRODUCT_REQUIRED / PRODUCT_UNAVAILABLE | Call list_products and select a returned product ID; inspect archived products if appropriate. Do not guess an ID. |
| Browser sign-in completes but the client remains disconnected | Confirm the remote URL is https://nabit.ai/mcp and the client supports Streamable HTTP plus OAuth. Retry the connection in that client. |
Credits and limits
| Code | What to do |
|---|---|
INSUFFICIENT_CREDITS | Compare required and available in the returned Credit details. Review existing holds; an owner/admin can use the website billing flow. |
DAILY_RECOMMENDATION_LIMIT | Wait until 00:00 UTC. Basic / Plus have 8 new batches per day, trials 4, including the first. The limit is shared across channels. |
TRIAL_CREDIT_LIMIT | The trial's Credit budget is exhausted; check plan options on the website. |
RATE_LIMIT / RATE_LIMITED | Reduce concurrent calls and retry with backoff. Honor retry timing if provided. See current limits. |
WORKSPACE_SPENDING_PAUSED / MEMBER_SPENDING_PAUSED | Ask an owner/admin to review the spending pause. |
WORKSPACE_MONTHLY_LIMIT / MEMBER_MONTHLY_LIMIT | Ask an owner/admin to review the workspace or member budget. A positive Credit balance does not bypass a budget. |
ACCOUNT_SPENDING_BLOCKED | Check the billing message and contact support about the account's payment review. |
CREDIT_RESULT_PENDING | Keep the existing request / snapshot ID and check its status. Credits remain reserved while the result is uncertain; do not start duplicate paid work. |
Pending, failed or missing recommendations
For a queued or running result, poll get_recommendation_batch with the returned snapshotId. RECOMMENDATIONS_PENDING means the batch is not ready to render yet. Space out polling and keep the same ID.
For RECOMMENDATIONS_FAILED, inspect the existing batch before requesting a retry. Some Hooks may have been delivered and can still be billed. Failed or timed-out work does not always mean the entire hold is immediately released. Read hold / commit / release.
For REFERENCE_UNAVAILABLE, use the original snapshotId and returned Hook ID. Older matching references may need their original snapshot when saving or sending feedback. Do not combine a Hook from one batch with another batch's ID.
An empty get_trending_videos result does not mean the global trend list is empty. That tool reads existing tracking for one product; it does not start tracking or expose the demo heat board.
Unsupported tools and display
CAPABILITY_RETIRED on start_research or get_research_status means the client is using an old workflow. Refresh its tool list and use request_recommendations / get_recommendation_batch.
MCP image/video generation is not available. Use Nabit AI Studio on the website, including on Basic, with the confirmed Credit quote. The implemented public /v1 routes cover recommendations and existing product trends only; see the HTTP reference. They use existing workspace OAuth; API keys are deferred to milestone 4. Local implementation does not mean these routes have been deployed.
For /v1, inspect both HTTP status and the JSON status: queued/running/failed batch states can use HTTP 200. Poll the returned snapshot rather than creating another batch. INVALID_INPUT, INVALID_BODY and BODY_LIMIT indicate invalid parameters/JSON or the existing 16,000-character body limit; use only documented fields, avoid duplicate query parameters and pass the token in the Authorization header. The docs-only local preview deliberately returns 404 for /v1; use the application runtime for these routes after integration. A 404 can also mean the product/snapshot is not available to the authorized workspace.
If reference cards do not render, use the returned viewing links in a signed-in browser. render_video_recommendations displays existing references, and requires an MCP Apps-capable client for its embedded view. It does not generate a video or grant access to public MP4 downloads.
Contact support
Send the tool name, error code, approximate time and timezone, client/version, product ID and snapshot ID if available through Contact Nabit. Describe whether the request was a retry and whether any Hooks were delivered. Redact tokens, authorization headers and unrelated personal data; do not send a full credential-bearing trace.