> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hany.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# Hany API Errors: Status Codes and Error Code Reference

> Hany uses standard HTTP status codes and structured JSON error bodies to help you identify and resolve problems in your integration.

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:

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

<ResponseField name="status" type="string">
  Always `"error"` for failed requests.
</ResponseField>

<ResponseField name="code" type="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.
</ResponseField>

<ResponseField name="message" type="string">
  A plain-English description of what went wrong, suitable for logging or displaying to internal users.
</ResponseField>

## 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](https://en.wikipedia.org/wiki/E.164) (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](mailto:support@hany.tools).               |

## Handling Errors

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

```javascript theme={null}
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
  }
}
```

<Tip>
  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.
</Tip>