> ## Documentation Index
> Fetch the complete documentation index at: https://pocketmusala.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Recover from common setup failures.

Every error response includes a stable error code, message, request id, and
troubleshooting state:

```json theme={null}
{
  "error": {
    "code": "missing_scope",
    "message": "Developer API key requires sync:write",
    "requestId": "weekly-profile-2026-06-08",
    "troubleshooting": {
      "code": "missing_scope",
      "severity": "error",
      "adminSummary": "The key does not have the permission needed for this sync.",
      "developerSummary": "Create or rotate a key with the required scope."
    }
  }
}
```

## Common Failures

| Symptom                    | Likely Cause                                                           | Recovery                                                |
| -------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------- |
| `missing_api_key`          | Authorization header is missing.                                       | Send `Authorization: Bearer <api_key>`.                 |
| `malformed`                | The key format is invalid.                                             | Re-copy the key from the PocketMusala portal.           |
| `revoked` or `expired`     | The key is no longer active.                                           | Rotate or create a new key in PocketMusala.             |
| `wrong_community`          | The key belongs to a different mosque.                                 | Use the mosque id selected in the portal for that key.  |
| `missing_scope`            | The key is valid but lacks read or write scope.                        | Create or rotate a key with the needed scope.           |
| `invalid_argument`         | Payload shape, field name, UUID, timestamp, or time format is invalid. | Compare the request body with the OpenAPI schema.       |
| `invalid_prayer_time`      | Prayer key or time format is unsupported.                              | Use a supported prayer key and `HH:mm` or `h:mm am/pm`. |
| `not_found`                | The endpoint, mosque, or row id is unavailable to the key.             | Check the path, mosque id, and resource id.             |
| `server_error` or `failed` | PocketMusala failed after validation.                                  | Retry with backoff and keep the request id for support. |

## What To Send Support

Send PocketMusala support:

* the mosque id;
* the key prefix, never the full key;
* request id;
* endpoint path and method;
* timestamp;
* redacted request body;
* error response body.

Do not email or paste the raw API key.