> For the complete documentation index, see [llms.txt](https://docs.themochi.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.themochi.app/troubleshooting-and-safety/diagnose-api-failures.md). # Troubleshoot API requests Identify the type of failure before changing a credential or retrying. Record only the status, method, path without private query values, UTC time, and `X-Request-ID`. Do not expose an authorization header, token, API key, request/response body, cursor, contact value, message content, or provider data in a prompt, log, screenshot, issue, or support message. Compare observed behavior with the [generated OpenAPI contract](https://openapi.gitbook.com/o/M0sgy6xKutCblHRqGmE5/spec/mochi-api.json) before changing a request. ## Start with these checks 1. Confirm the canonical docs and OpenAPI contract are reachable and describe the operation. 2. Confirm the expected organization, connection method, scope, and any required member role or rollout approval. 3. Use the HTTP status as the main category. Use a typed error value when present. Do not make decisions from human wording. 4. Apply only the current [Errors](/troubleshooting-and-safety/errors.md), [Rate limits](/troubleshooting-and-safety/rate-limits.md), and [Idempotency](/troubleshooting-and-safety/idempotency.md) rules. 5. After a correction, make the smallest safe read or verification request. Do not broaden scopes or expose a credential to “debug” it. ## `401`: the connection is not accepted The credential is missing, malformed, expired, invalid, revoked, or unavailable. For CLI browser approval, inspect `mochi auth status` and follow the current CLI error code. Do not read its credential storage. For an API key, ask the operator to check the secret-manager setting and key status without printing the value. For MCP, use the existing reconnect screen only when that connection is invalid. Do not export its token. Repeated `401` responses are not retryable until the authentication cause changes. ## `403`: the connection lacks permission Mochi accepted the connection, but it lacks a required permission or role. Compare the current OpenAPI scope with the approved task. If the permission was intentionally omitted, stop and request a separate, limited approval. A required member role or organization-principal identity cannot be bypassed by repeating the request. Never solve `403` by borrowing another person's credential or asking for a broader token in a prompt. ## `404`: the resource or feature is unavailable The resource may not exist, may belong to another organization, or may not be enabled. Mochi intentionally does not reveal whether another organization's resource exists. Recheck only non-secret IDs and availability. Do not try nearby IDs or assume the problem is authentication. ## `409`: another request or state conflicts For a write that supports safe retries, the same request may still be running. Follow [Retry writes safely](/troubleshooting-and-safety/idempotency.md) and preserve the key, method, path, and body. For a state conflict such as an overwrite, read the current resource and stop the write sequence. Get a new approved plan before changing it. ## `429`: too many requests Wait for the current `Retry-After` value. Add a small random delay when workers share a key. Limit attempts and the number of requests running at once. Do not rotate credentials to evade a limit. Staying under the API limit does not guarantee that Mochi will accept an outbound message. ## Network or `5xx` failure For a read, retry a limited number of times and wait longer after each failure. For a write, first check whether the current documentation defines a safe retry. If the provider or application result is unknown, do not invent a new idempotency key. If the contract does not define safe behavior, stop and ask for help with sanitized request details. ## Ask for support safely Provide support with: * documentation/OpenAPI version or URL; * UTC timestamp; * HTTP method and sanitized path; * status and typed error code, if present; * `X-Request-ID`; * connection method, organization identifier, and non-secret key or connection label; and * what safe verification was attempted. If a credential may have been exposed, stop using it, remove the exposed copy where possible, and ask the operator to revoke or rotate it through the supported UI. Do not include the credential itself in the incident record. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.themochi.app/troubleshooting-and-safety/diagnose-api-failures.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.