Error Responses

All API errors follow a consistent format. This page documents common error responses.

Error Format

All errors return a JSON response with this structure:

{
  "success": false,
  "error": "Error message description",
  "code": "ERROR_CODE"
}

HTTP Status Codes

Status	Description
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`402`	Payment Required - Insufficient credits
`403`	Forbidden - Access denied
`404`	Not Found - Resource doesn't exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

Common Errors

401 Unauthorized

Invalid API Key

{
  "success": false,
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Missing Authorization Header

{
  "success": false,
  "error": "Authorization header is required",
  "code": "MISSING_AUTH"
}

400 Bad Request

Missing Phone

{
  "success": false,
  "error": "Phone, message, and sender ID are required",
  "code": "MISSING_PHONE"
}

Invalid Phone Number Format

{
  "success": false,
  "error": "Invalid phone number format: 12345. Use a valid Ghana number such as 0200000000, 233200000000, or +233200000000.",
  "code": "INVALID_PHONE"
}

Missing Message

{
  "success": false,
  "error": "Message content is required",
  "code": "MISSING_MESSAGE"
}

Message Too Long

{
  "success": false,
  "error": "Message exceeds maximum length of 918 characters",
  "code": "MESSAGE_TOO_LONG"
}

Invalid Sender ID

{
  "success": false,
  "error": "Sender ID 'InvalidName' is not approved",
  "code": "INVALID_SENDER_ID"
}

402 Payment Required

Insufficient Credits

{
  "success": false,
  "error": "Insufficient credits. Required: 50, Available: 10",
  "code": "INSUFFICIENT_CREDITS"
}

403 Forbidden

Sender ID Not Owned

{
  "success": false,
  "error": "Sender ID does not belong to user or does not exist",
  "code": "SENDER_ID_NOT_OWNED"
}

429 Too Many Requests

Rate Limit Exceeded

{
  "success": false,
  "error": "Rate limit exceeded. Please wait 60 seconds.",
  "code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 60
}

500 Internal Server Error

Server Error

{
  "success": false,
  "error": "An unexpected error occurred. Please try again later.",
  "code": "INTERNAL_ERROR"
}

Handling Errors

Example error handling in JavaScript:

try {
  const response = await fetch("https://kixon.app/api/send-sms", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(data),
  });
 
  const result = await response.json();
 
  if (!response.ok) {
    switch (response.status) {
      case 401:
        console.error("Authentication failed:", result.error);
        break;
      case 402:
        console.error("Insufficient credits:", result.error);
        break;
      case 429:
        console.error("Rate limited. Retry after:", result.retry_after);
        break;
      default:
        console.error("API error:", result.error);
    }
    return;
  }
 
  console.log("SMS sent:", result.messageId);
} catch (error) {
  console.error("Network error:", error);
}