Getting started

Errors and limits

Errors are boring on purpose: one stable envelope, machine-readable codes, and a request id you can hand to support. Writes are idempotent so retries are always safe.

The error envelope

error.response

{
  "error": {
    "code": "CHANNEL_NOT_CONNECTED",
    "message": "instagram is not connected for this business. Connect it in the app first.",
    "requestId": "req_..."
  }
}

Branch on error.code, show error.message to humans, and log error.requestId.

The codes

UNAUTHORIZED	401	Missing or invalid key.
FORBIDDEN	403	The key cannot act here.
SCOPE_MISSING	403	The key lacks the scope this endpoint needs.
NOT_FOUND	404	No such resource in this business.
VALIDATION_ERROR	400	The body or params failed validation.
RATE_LIMITED	429	Over a per-key hourly limit. Honor Retry-After.
APPROVAL_REQUIRED	409	A review-mode post must be approved before publishing.
CHANNEL_NOT_CONNECTED	409	No connected channel for that platform. Channel OAuth happens in the app, by design.
INSUFFICIENT_CREDITS	job	Not enough credits for a generation. In practice this lands as a failed job with code insufficient_credits; nothing is charged.
IDEMPOTENCY_CONFLICT	409	The same Idempotency-Key arrived with a different body.
CONFLICT	409	The request collides with in-flight work, for example the same Idempotency-Key while the first attempt is still running.
FEATURE_UNAVAILABLE	409	The capability is not enabled for this account or platform yet.
INTERNAL_ERROR	500	Our side. Retry with the same Idempotency-Key, or hand support the requestId.

Rate limits

Per key, per hour:

600 general requests.
60 AI generations.
20 outward writes (publish, approve, schedule).

The outward-write limit is deliberately the tightest one: it is the blast radius that reaches your audience.

Every response carries x-ratelimit-limit, x-ratelimit-remaining, and x-ratelimit-reset (seconds), plus Retry-After on a 429, so a client never has to guess. The x-request-id header rides along on everything.

Idempotency

Send an Idempotency-Key header on writes. The same key replays the original response for 24 hours instead of double-charging credits or double-publishing a post.

idempotent.write

curl -X POST https://api.taka.ai/v1/public/posts \
  -H "Authorization: Bearer taka_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-weekend-special-1" \
  -d '{"platform": "instagram", "idea": "Weekend special"}'

Retry rule

Timeout or 5xx on a write? Retry with the same key, never a fresh one. The reply you get is the reply the first attempt earned.