Cancel

Cancels an active One-Time Password (OTP). Only OTPs in a pending state can be cancelled. Once an OTP is verified, expired, failed, or consumed, it cannot be cancelled.

Endpoint

POST /otp/cancel

Authentication: Tenant authentication required

Description

The cancel endpoint cancels an active OTP, preventing it from being used. This endpoint is useful when a user no longer needs an OTP (e.g., they received a new OTP or decided not to proceed with the operation).

After successful cancellation:

• The OTP status is changed from pending to cancelled
• The OTP can no longer be verified or used
• A success response is returned

If the OTP is already cancelled, the endpoint returns success without performing any additional operations.

Important: Only OTPs in a pending state can be cancelled. OTPs that are verified, expired, failed, or consumed cannot be cancelled.

Request

Body

{
  "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "scope": "reset_password"
}

Parameter	Type	Required	Description	Constraints
id	string	Yes	OTP token ID (from create endpoint)	Non-empty string
scope	string	Yes	OTP scope/purpose	Must be one of: email_verification, phone_verification, reset_password, otp_signin

Response

Status Code: 201 Created

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "data": {
    "success": true
  }
}

Field	Type	Description
success	boolean	Always true on success

Rate Limiting

Rate limiting is applied to prevent abuse and ensure system stability. The cancel endpoint has the following rate limits:

Limit Type	Rate	Window
Per IP	30 requests	1 hour

When rate limits are exceeded, the API returns a 429 Too Many Requests status code.

For information about rate limit headers, see Rate Limiting in the overview.

Errors

For detailed explanations of all error codes, see the Error Codes page where you can find all system errors.

400 Bad Request - Validation Error

Occurs when the request body fails validation. Common causes include missing required fields or invalid scope value.

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "The provided request data is invalid.",
    "code": "VALIDATION_ERROR",
    "status": 400,
    "validation": {
      "id": "Required",
      "scope": "Invalid enum value"
    }
  }
}

Field	Error Message	Cause
id	Required	OTP ID is missing
scope	Invalid enum value	Scope is not one of the allowed values

404 Not Found - OTP Not Found

Occurs when the OTP with the provided ID and scope does not exist in the system.

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "OTP not found",
    "code": "OTP_NOT_FOUND",
    "status": 404
  }
}

422 Unprocessable Entity - OTP Not Cancelable

Occurs when the OTP cannot be cancelled because it is not in a cancelable state. Only OTPs in a pending state can be cancelled. OTPs that are verified, expired, failed, or consumed cannot be cancelled.

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "OTP is not cancelable",
    "code": "OTP_NOT_CANCELABLE",
    "status": 422
  }
}

429 Too Many Requests - Rate Limit Exceeded

Occurs when the rate limit is exceeded. See Rate Limiting section for details.

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "Too many requests",
    "code": "TOO_MANY_REQUESTS",
    "status": 429
  }
}

500 Internal Server Error

Occurs when an internal error happens during OTP cancellation. Common causes include tenant configuration issues or other unexpected system state.

Error codes:

• TENANT_NOT_CONFIGURED - Tenant OTP configuration is missing or invalid
• INTERNAL_SERVER - General internal server error

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "Tenant OTP configuration is missing",
    "code": "TENANT_NOT_CONFIGURED",
    "status": 500
  }
}

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "Something went wrong on our side.",
    "code": "INTERNAL_SERVER",
    "status": 500
  }
}

Notes

• Only OTPs in a pending state can be cancelled