Skip to main content

Invitation Error Codes

The invitation API throws specific errors when operations fail. This table summarizes the most common error codes.

Error Code Reference​

CodeScenario
400 BAD_REQUESTMissing required fields or invalid ID
404 NOT_FOUNDInvitation not found or not in the expected state
409 CONFLICTDuplicate token when creating an invitation
500 INTERNAL_SERVER_ERRORUnexpected database failure

Lifecycle Operations​

Lifecycle operations have specific error behaviors:

Soft Delete​

DELETE /invitations/:id

  • 404: Invitation not found
  • 400: Invitation already deleted

Restore​

POST /invitations/:id/restore

  • 404: Invitation not found
  • 400: Invitation is not deleted (cannot restore)

Permanent Delete​

DELETE /invitations/:id/permanent

  • 404: Invitation not found
  • 400: Invitation must be soft-deleted first

Common Scenarios​

Creating an Invitation​

// Error: 409 CONFLICT
{
  "statusCode": 409,
  "message": "Invitation with this token already exists",
  "error": "Conflict"
}

Accepting an Expired Invitation​

// Error: 400 BAD_REQUEST
{
  "statusCode": 400,
  "message": "Invitation has expired",
  "error": "Bad Request"
}

Accessing a Deleted Invitation​

// Error: 404 NOT_FOUND
{
  "statusCode": 404,
  "message": "Invitation not found",
  "error": "Not Found"
}

Troubleshooting​

  1. Token conflicts: Ensure invitation tokens are unique. The system generates UUIDs by default.
  2. State transitions: Follow the invitation lifecycle: pending → accepted/declined/expired → deleted.
  3. Permission errors: Verify the user has INVITATION_MGMT capabilities.