Troubleshooting

Recover from common setup failures.

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

{
  "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.