Use the endpoint response and the invitation’s current state together. Do not log or paste plaintext invitation tokens while diagnosing a failure.
Error Responses
All endpoints follow the standard error format:
400 Bad Request
{
"error": "User is already a member of this organization",
"error_code": "BAD_REQUEST",
"timestamp": "2025-01-15T10:30:00Z"
}
401 Unauthorized
{
"error": "Missing or invalid Authorization header",
"error_code": "UNAUTHORIZED",
"timestamp": "2025-01-15T10:30:00Z"
}
403 Forbidden
{
"error": "Organization admin or owner role required",
"error_code": "FORBIDDEN",
"timestamp": "2025-01-15T10:30:00Z"
}
404 Not Found
{
"error": "Invitation not found or already processed",
"error_code": "NOT_FOUND",
"timestamp": "2025-01-15T10:30:00Z"
}
Symptom guide
| Symptom | Check | Resolution |
|---|---|---|
| Invitation creation returns 400 | Existing membership, pending duplicate, and requested role | Remove the duplicate workflow or submit one of owner, admin, or member |
| Invitation creation or listing returns 403 | Caller organization role | Use an owner or admin organization-management token |
| Acceptance says expired | The invitation expiry timestamp | Create a new invitation; expired invitations cannot be reactivated |
| Acceptance says team limit reached | Organization tier and max-users override | Increase capacity or remove an unused member before retrying |
| Accept or decline cannot find the invitation | Token value, prior processing, and cancellation state | Use the one-time plaintext token from the email and issue a new invitation when already processed |
| Email never arrives | Organization SMTP configuration and delivery logs | Correct SMTP, then create a fresh invitation or deliver the one-time link securely |
Safe diagnosis checklist
- Reproduce with the exact documented method and path.
- Confirm whether the endpoint is public, user-authenticated, or owner/admin-only.
- Inspect the status and expiry without exposing the plaintext token.
- Check member limits before retrying acceptance.
- Correlate invitation webhook and audit events.
- Create a new invitation rather than trying to reactivate a terminal state.