Error Responses

JSON errors

Errors use an HTTP status code and JSON body. The message can be a string or a list of validation messages.

{
  "message": "Invalid API key",
  "error": "Unauthorized",
  "statusCode": 401
}

Example validation response:

{
  "message": ["OTP must be between 4 and 8 numeric digits"],
  "error": "Bad Request",
  "statusCode": 400
}

Status codes

HTTP status	Common cause	Action
400 Bad Request	Invalid phone or OTP, unknown body fields, insufficient balance, blocked destination, daily limit, or unapproved introduction recording.	Read message, fix the input or account condition, then retry if appropriate.
401 Unauthorized	Missing, invalid, replaced, or revoked API key.	Check the X-API-Key header.
403 Forbidden	Inactive account, package without API access, or no usable sender.	Check your account, package, and sender access.
404 Not Found	Unknown call ID or a call outside your account.	Use the exact callId returned for your account.
409 Conflict	An idempotency key was used for a different destination or mode.	Use a fresh key for a new logical request.
5xx	Temporary application or upstream failure.	Retry cautiously with the same idempotency key and backoff.

Troubleshooting

• Send JSON with Content-Type: application/json.
• Send otp as a string and repeatCount as an integer.
• Use the base URL https://api.kokilcloud.com/v1 and the X-API-Key header.
• A 202 response means the call was accepted, not that it was answered.
• For support, include the callId and error message. Do not include your complete API key or a live OTP.