Getting started

Errors & rate limits

The API uses standard HTTP status codes. Errors always have a JSON body with a detail field.

Error format

Most errors carry a human-readable message you can show or log as-is:

404

{
  "detail": "Agent not found"
}

Validation errors (422) return a list instead, one entry per problem. loc points at the field:

422

{
  "detail": [
    {
      "type": "missing",
      "loc": [
        "body",
        "llm_model"
      ],
      "msg": "Field required",
      "input": {}
    },
    {
      "type": "extra_forbidden",
      "loc": [
        "body",
        "tenant_id"
      ],
      "msg": "Extra inputs are not permitted",
      "input": "..."
    }
  ]
}

Status codes

200

The request succeeded.

201

Created

A resource was created (agents, tools, invitations).

400

Bad request

The request is well-formed but not allowed, e.g. an unsupported language for the STT provider.

401

Unauthorized

The API key is missing, invalid, revoked or expired.

402

Plan limit

Your plan doesn't allow this, e.g. no agent slots left. The message says what to upgrade.

403

Forbidden

The workspace is suspended.

404

Not found

The resource doesn't exist, or belongs to another workspace.

409

Conflict

The request clashes with the current state, e.g. a duplicate tool or a closed WhatsApp window.

422

Validation error

The body or query failed validation: a missing field, wrong type, or unknown field.

429

Too many requests

You hit the rate limit. Wait for Retry-After seconds.

500

Server error

Something went wrong on our side. Safe to retry with backoff.

502

Upstream error

A provider we depend on (e.g. WhatsApp) failed or couldn't be reached.

Rate limits

Each API key can make 120 requests per minute. The window resets at the start of every minute. Every response tells you where you stand:

Header	Description
`X-RateLimit-Limit`	Requests allowed per minute for this key.
`X-RateLimit-Remaining`	Requests left in the current minute.
`X-RateLimit-Reset`	Seconds until the window resets.
`Retry-After`	On 429 only: seconds to wait before retrying.

Over the limit, you get:

429

{
  "detail": "Rate limit exceeded"
}

For syncs, page with limit and pass updated_since where available, instead of re-reading everything. Need a higher limit? Write to support@tarangnow.com.

Retrying

Retry 429, 500 and 502 with exponential backoff. For 429, wait at least Retry-After seconds.
Don't retry other 4xx errors unchanged -- fix the request first.
Creating resources isn't idempotent. If a create request times out, list the resources before retrying so you don't make a duplicate.