Developers
Errors and rules
Rules that work the same on every endpoint: error format, rate limits, safe retries, pagination, language and versioning.
Error format
Errors are returned as JSON; code is for machines and doesn't depend on language, message can be shown to users.
HTTP/1.1 400 Bad Request
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1793955660
Content-Type: application/json
{ "error": { "code": "validation_error", "message": "to: This field is required" } }HTTP status 400 (validation; an unknown field is named in the message), 401 (authentication), 403 (plan/scope), 404, 409 (action not possible in this state), 422 (content policy: content_policy), 429 (rate limit or monthly message quota: message_quota_exceeded), 502 (channel error).
| Status | Meaning |
|---|---|
400 | Invalid request: a missing or wrong field, or an unknown field name (validation_error). |
401 | The API key is missing, invalid or revoked (unauthorized). |
403 | Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended. |
404 | The record doesn't exist or this key can't access it (not_found). |
409 | The action isn't possible in this state; the code gives the reason. |
413 | The plan's storage quota is full (storage_quota_exceeded); delete images or upgrade the plan. |
422 | Blocked by the content policy (content_policy). |
429 | A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header. |
502 | A channel or external service failed (channel_error). |
503 | Background jobs have stopped or the service is temporarily unavailable. |
Common codes
| Code | Status | What to do |
|---|---|---|
validation_error | 400 | Fix the field named in the message; don't retry. |
unauthorized | 401 | Check the key or refresh the OAuth token. |
scope | 403 | Create a new key with the scope you need. |
plan_limit | 403 | A plan limit or API access: upgrade the plan. |
forbidden_role | 403 | The action needs a higher role. |
email_not_verified | 403 | To create campaigns, whoever created the key (for OAuth, who granted access) must verify their email in the dashboard. |
opted_out, consent_required | 403 | The contact hasn't given consent; the message isn't sent. |
bot_plan_restricted | 403 | The bot is over your plan's limit; API sending resumes when you upgrade, manual replies from the dashboard stay available. |
not_found | 404 | Check the ID and the key's bot access. |
idempotency_conflict | 409 | The same key was used with a different body; generate a new key. |
idempotency_in_progress | 409 | The first request is still running; wait for Retry-After. |
content_policy | 422 | Change the text to comply with the policy. |
rate_limited | 429 | Wait for Retry-After, then retry. |
message_quota_exceeded | 429 | The monthly message quota is used up; Retry-After is the time until it resets. |
template_required, template_unsupported | 400 | The WhatsApp 24-hour window is closed: send an approved template; templates only work on WhatsApp. |
invalid_api_key | 400 | The external (AI) provider key you entered couldn't be verified; check the key. |
organization_suspended | 403 | The organization is suspended and API access is off; contact support. |
limit_reached, webhook_limit, open_limit | 409 | A resource limit was reached; delete or resolve unused ones, or upgrade the plan. |
feature_disabled | 409 | The feature is off for this organization; turn it on in the dashboard. |
not_connected, channel_not_configured, bot_inactive | 409 | The bot isn't connected to its channel or isn't active; connect and enable it in the dashboard. |
https_required | 409 | The server address isn't HTTPS, so the Telegram webhook can't be set up. |
bot_removed, bot_permission | 409 | On Telegram the bot was removed from the community or isn't an admin; add it back and grant permissions. |
ai_not_configured | 409 | No AI provider or key is set; complete the AI settings in the dashboard. |
message_not_retryable | 409 | Only failed outgoing messages can be retried, up to 5 times. |
campaign_locked, campaign_started, campaign_finished | 409 | The campaign started or finished sending and can't be changed; create a new campaign. |
invalid_status, schedule_conflict, post_locked | 409 | The record's current state doesn't allow this; read it again and decide. |
contact_exists, field_exists, shortcut_exists, already_member | 409 | The same record already exists; use or update the existing one. |
media_in_use | 409 | The image is in use; remove it from where it's used first. |
storage_quota_exceeded | 413 | The plan's storage quota is full; delete images or upgrade the plan. Usage is in the storage field of getUsage. |
member_not_changeable, member_not_removable, not_team_member, bot_access_denied | 409 | The owner can't be changed or removed; the assignee must be on the team and have access to the bot's conversations. |
webhook_inactive | 409 | The webhook is off; turn it on first with POST /api/v1/webhooks/{id}/enable. |
ai_quota_exceeded | 429 | The monthly AI reply quota is used up; buy an extra pack or wait for the new month. |
ai_error, ai_provider_unreachable | 502 | The AI provider didn't respond; try again a bit later. |
channel_error | 502 | A channel error; you can retry with Idempotency-Key. |
Rate limits
Each key allows 120 requests per minute; invalid keys count per IP at 60 per minute, scope and plan 403s count per organization at 120 per minute, and MCP requests fall under the same limits. All keys and OAuth connections of an organization also share a per-minute and daily (UTC) limit based on the plan; a 429 at that layer names it in the X-RateLimit-Scope header (organization or organization_day).
X-RateLimit-Limit: the per-minute limitX-RateLimit-Remaining: requests left in the windowX-RateLimit-Reset: when the window resets (Unix seconds)Retry-After: seconds to wait on a 429; for the monthly quota, the time until it resets
Responses, including errors, carry these headers. If you keep getting 429s, follow the wait time; retrying right away doesn't extend the limit but wastes requests.
import { Hiboty, HibotyHatasi } from "@hiboty/sdk";
const hiboty = new Hiboty({ apiKey: process.env.HIBOTY_API_KEY });
const botId = process.env.BOT_ID;
async function sendWithRetry(to, message) {
for (let attempt = 0; attempt < 3; attempt++) {
try {
return await hiboty.sendMessage({ bot_id: botId, to, message }, { idempotencyKey: `note-${to}` });
} catch (err) {
if (!(err instanceof HibotyHatasi) || err.status !== 429 || attempt === 2) throw err;
await new Promise((r) => setTimeout(r, (err.retryAfter ?? 1) * 1000));
}
}
}
console.log(await sendWithRetry("123456789", "Hello!"), hiboty.rateLimit);Safe retries (Idempotency-Key)
Endpoints that support it are marked in the reference (POST /api/v1/messages, POST /api/v1/campaigns and most write endpoints). The Idempotency-Key header is 1-255 visible ASCII characters. A key is valid for 24 hours per organization and endpoint: the same key with the same body returns the first response unchanged (Idempotency-Replayed: true), so the message isn't sent twice and quota isn't used twice. A different body returns 409 idempotency_conflict; while the first request is running you get 409 idempotency_in_progress with Retry-After. 5xx and 429 responses aren't stored, so you can retry with the same key.
curl -X POST "https://hiboty.com/api/v1/messages" \
-H "Authorization: Bearer $HIBOTY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-10482" \
-d '{"bot_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","to":"123456789","message":"Hello!"}'Pagination
List endpoints accept limit (1–200) and cursor; a different default or maximum is listed in the reference. Send the next_cursor from the response back as cursor unchanged; it is null on the last page. A limit that isn't an integer returns 400. In the SDKs, paginate walks all of these lists.
curl "https://hiboty.com/api/v1/contacts?limit=50" -H "Authorization: Bearer $HIBOTY_API_KEY"
# { "data": [ ... ], "next_cursor": "eyJ0Ijoi..." }
curl "https://hiboty.com/api/v1/contacts?limit=50&cursor=eyJ0Ijoi" -H "Authorization: Bearer $HIBOTY_API_KEY"Language
Error messages are in Turkish by default; use ?lang=en or Accept-Language: en for English. The code field is always the same. In the SDKs, set it with the lang option.
curl "https://hiboty.com/api/v1/bots?lang=en" -H "Authorization: Bearer $HIBOTY_API_KEY"
curl "https://hiboty.com/api/v1/bots" -H "Authorization: Bearer $HIBOTY_API_KEY" -H "Accept-Language: en"Versioning policy
The API and SDKs use semantic versioning; the current version is info.version in the OpenAPI document. Under v1 only backward-compatible additions are made: new endpoints, optional fields or response fields. Your client should ignore unknown response fields. Removing a field or changing its meaning happens in a new major version (v2) and is announced in advance with a transition period. Fixes that reject incorrect usage (such as a misspelled field returning 400) can ship in a minor version and are listed in the release notes.
Channel webhooks
Telegram and WhatsApp webhooks are set up automatically by Hiboty and verified by signature. Use outgoing webhooks to forward events to your own systems.