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
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).

StatusMeaning
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
401The API key is missing, invalid or revoked (unauthorized).
403Missing 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.
404The record doesn't exist or this key can't access it (not_found).
409The action isn't possible in this state; the code gives the reason.
413The plan's storage quota is full (storage_quota_exceeded); delete images or upgrade the plan.
422Blocked by the content policy (content_policy).
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
502A channel or external service failed (channel_error).
503Background jobs have stopped or the service is temporarily unavailable.

Common codes

CodeStatusWhat to do
validation_error400Fix the field named in the message; don't retry.
unauthorized401Check the key or refresh the OAuth token.
scope403Create a new key with the scope you need.
plan_limit403A plan limit or API access: upgrade the plan.
forbidden_role403The action needs a higher role.
email_not_verified403To create campaigns, whoever created the key (for OAuth, who granted access) must verify their email in the dashboard.
opted_out, consent_required403The contact hasn't given consent; the message isn't sent.
bot_plan_restricted403The bot is over your plan's limit; API sending resumes when you upgrade, manual replies from the dashboard stay available.
not_found404Check the ID and the key's bot access.
idempotency_conflict409The same key was used with a different body; generate a new key.
idempotency_in_progress409The first request is still running; wait for Retry-After.
content_policy422Change the text to comply with the policy.
rate_limited429Wait for Retry-After, then retry.
message_quota_exceeded429The monthly message quota is used up; Retry-After is the time until it resets.
template_required, template_unsupported400The WhatsApp 24-hour window is closed: send an approved template; templates only work on WhatsApp.
invalid_api_key400The external (AI) provider key you entered couldn't be verified; check the key.
organization_suspended403The organization is suspended and API access is off; contact support.
limit_reached, webhook_limit, open_limit409A resource limit was reached; delete or resolve unused ones, or upgrade the plan.
feature_disabled409The feature is off for this organization; turn it on in the dashboard.
not_connected, channel_not_configured, bot_inactive409The bot isn't connected to its channel or isn't active; connect and enable it in the dashboard.
https_required409The server address isn't HTTPS, so the Telegram webhook can't be set up.
bot_removed, bot_permission409On Telegram the bot was removed from the community or isn't an admin; add it back and grant permissions.
ai_not_configured409No AI provider or key is set; complete the AI settings in the dashboard.
message_not_retryable409Only failed outgoing messages can be retried, up to 5 times.
campaign_locked, campaign_started, campaign_finished409The campaign started or finished sending and can't be changed; create a new campaign.
invalid_status, schedule_conflict, post_locked409The record's current state doesn't allow this; read it again and decide.
contact_exists, field_exists, shortcut_exists, already_member409The same record already exists; use or update the existing one.
media_in_use409The image is in use; remove it from where it's used first.
storage_quota_exceeded413The 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_denied409The owner can't be changed or removed; the assignee must be on the team and have access to the bot's conversations.
webhook_inactive409The webhook is off; turn it on first with POST /api/v1/webhooks/{id}/enable.
ai_quota_exceeded429The monthly AI reply quota is used up; buy an extra pack or wait for the new month.
ai_error, ai_provider_unreachable502The AI provider didn't respond; try again a bit later.
channel_error502A 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 limit
  • X-RateLimit-Remaining: requests left in the window
  • X-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.