Hany API Errors: Status Codes and Error Code Reference

Hany uses standard HTTP status codes to indicate whether a request succeeded or failed. Any response with a 4xx or 5xx status code includes a JSON body that gives you a machine-readable error code and a human-readable message — so your integration can respond intelligently without parsing free-form text.

Error Response Format

Every error response follows this consistent shape:

{
  "status": "error",
  "code": "invalid_recipient",
  "message": "The recipient phone number is not in a valid E.164 format."
}

string

Always "error" for failed requests.

string

A stable, snake_case identifier for the error type. Use this field in your application logic — the message field is for humans and may change.

string

A plain-English description of what went wrong, suitable for logging or displaying to internal users.

HTTP Status Codes

Status	Meaning
`200 OK`	The request succeeded.
`201 Created`	A resource was successfully created (e.g., a new Sender ID was registered).
`400 Bad Request`	The request is malformed or contains invalid parameters.
`401 Unauthorized`	The `Authorization` header is missing or contains an invalid API key.
`403 Forbidden`	The API key is valid but does not have permission to perform this action.
`404 Not Found`	The requested resource does not exist.
`422 Unprocessable Entity`	The request is well-formed but failed validation (e.g., insufficient credits).
`429 Too Many Requests`	You have exceeded the rate limit. Slow down and retry.
`500 Internal Server Error`	An unexpected error occurred on Hany’s servers. Contact support if it persists.

Common Error Codes

Error Code	HTTP Status	Description
`unauthorized`	`401`	API key is missing or invalid. Check your `Authorization` header.
`forbidden`	`403`	Your API key does not have permission to perform this action.
`invalid_recipient`	`400`	The recipient phone number is not in valid E.164 format (e.g., `+233XXXXXXXXX`).
`invalid_sender_id`	`400`	The specified Sender ID is not registered on your account or has not been approved.
`insufficient_credits`	`422`	Your account does not have enough credits to send this message or campaign.
`rate_limit_exceeded`	`429`	You are sending requests too quickly. Implement backoff and retry.
`message_too_long`	`400`	The message body exceeds the maximum allowed character length.
`server_error`	`500`	An internal error occurred. Retry the request or contact support@hany.tools.

Handling Errors

Check the HTTP status code first, then inspect error.code to take the appropriate action in your integration:

const response = await fetch('https://api.hany.tools/v1/sms/send', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.HANY_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ to: '+233XXXXXXXXX', from: 'YourBrand', message: 'Hello!' })
});

if (!response.ok) {
  const error = await response.json();
  console.error(`Error ${response.status}: ${error.code} — ${error.message}`);

  // Handle specific error codes
  if (error.code === 'insufficient_credits') {
    // Redirect user to top up their credits
  } else if (error.code === 'invalid_recipient') {
    // Prompt the user to correct the phone number
  } else if (error.code === 'rate_limit_exceeded') {
    // Back off and schedule a retry
  }
}

When retrying after 429 Too Many Requests or 500 Internal Server Error responses, use exponential backoff — wait 1 second before the first retry, 2 seconds before the second, 4 seconds before the third, and so on. This avoids hammering the API while it recovers and reduces the chance of triggering the rate limit again.

Overview

SMS

Webhooks

Hany API Errors: Status Codes and Error Code Reference

Error Response Format

HTTP Status Codes

Common Error Codes

Handling Errors

​Error Response Format

​HTTP Status Codes

​Common Error Codes

​Handling Errors

Error Response Format

HTTP Status Codes

Common Error Codes

Handling Errors