Resend

Resends a One-Time Password (OTP) to the recipient. The OTP must be in a pending state, the resend interval must have expired, and the maximum number of resends must not have been reached.

Endpoint

POST /otp/resend

Authentication: Tenant authentication required

Description

The resend endpoint resends an existing OTP to the recipient via the original delivery method (email or SMS). This endpoint is useful when a user did not receive the OTP or needs a new code.

After successful resend:

• The OTP resend count is incremented
• The lastSentAt timestamp is updated
• The OTP code is resent to the recipient via the original method (email or SMS)
• A success response is returned

Important: The OTP must be in a pending state to be resent. Additionally, the resend interval (default: 60 seconds) must have expired since the last send, and the maximum number of resends (default: 3) must not have been reached.

Note: In the staging environment, OTP codes are not sent via email or SMS. Instead, they are shared in the webmixhub-otp Slack channel for testing purposes.

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 resend 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 Resend Error

Occurs when the OTP cannot be resent. This includes cases where the resend interval has not expired or the maximum number of resends has been reached.

Error codes:

• OTP_RESEND_INTERVAL_NOT_EXPIRED - The resend interval (default: 60 seconds) has not expired since the last send
• OTP_MAX_RESENDS_REACHED - The maximum number of resends (default: 3) has been reached

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "OTP resend interval not expired",
    "code": "OTP_RESEND_INTERVAL_NOT_EXPIRED",
    "status": 422
  }
}

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "OTP has reached the maximum number of resends",
    "code": "OTP_MAX_RESENDS_REACHED",
    "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 resend. 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 resent
• The resend interval (default: 60 seconds) must expire before another resend is allowed
• The maximum number of resends (default: 3) cannot be exceeded