Errors & Statuses

Everything served under https://api.graine.ai/v2 answers failures with one envelope and one integer code table. This page is the reference for both, plus the status enums you will poll against.

The error envelope

Every 4xx and 5xx under /v2 has exactly this body. No nesting, no detail key, no validation array:

{
  "error": 1200,
  "message": "Agent not found."
}

• error is a stable integer from the table below. Branch on it.
• message is a single human-readable sentence ending in a period. It never contains a stack trace, another system's response body, a database query or a phone number. Do not branch on it — the wording can change.
• A successful response never carries an error key.

The HTTP status follows from the integer code: each code has one status, with one exception — error 1000 also arrives as 405, 411, 413 or 415, the statuses HTTP defines for those cases (see the table below). Switch on the code and you never need the exception.

HTTP status codes

Error code table

1000 — invalid request

400. The request parsed, but the values do not make sense together, or a value is outside what this API accepts.

{
  "error": 1000,
  "message": "Unknown status 'answered'. Valid values are: balance-low, busy, call-disconnected, canceled, completed, error, failed, in-progress, initiated, no-answer, queued, rescheduled, ringing, scheduled, stopped, voice-mail, voice_mail, voicemail."
}

Other real 1000 messages include "The uploaded CSV file is empty.", "The uploaded CSV file has no header row.", "The request body must be a JSON object.", "No contacts were supplied.", and "Invalid value for 'direction': expected one of inbound, outbound."

1001 — validation failed

422. Schema validation rejected the request. The message is built from the first validation failure and names the field the way you wrote it — the body / query / path prefix is stripped.

{
  "error": 1001,
  "message": "Invalid value for 'page_size': ensure this value is less than or equal to 100."
}

1002 — missing parameter

400. A required parameter is absent.

{
  "error": 1002,
  "message": "Missing required parameter 'agent_id'."
}

1100 — unauthorized

401. Three distinct causes share this code, each with its own message: no Authorization header, a credential that is not a recognised key, or a key whose status is not active.

{
  "error": 1100,
  "message": "Missing bearer token. Send Authorization: Bearer gat_..."
}

{
  "error": 1100,
  "message": "Invalid API key. A key looks like 'gat_' followed by 43 characters; check yours was copied in full."
}

{
  "error": 1100,
  "message": "API key is inactive."
}

1101 — session token rejected

401. You sent a bearer credential that does not start with gat_ — almost always a dashboard session token pasted into an API client. This is checked before anything else, so the answer is immediate.

{
  "error": 1101,
  "message": "A browser session token is not a public API key. Authenticate with Authorization: Bearer gat_..."
}

1102 — forbidden

403. Your key is real, but it is not entitled to this. Three real messages:

{
  "error": 1102,
  "message": "This API key is not authorized for that organization."
}

The organization_id query parameter is optional on most routes, and any value other than your own key's organization is a hard 403 — never a silent override.

{
  "error": 1102,
  "message": "This API key is not bound to an organization."
}

{
  "error": 1102,
  "message": "This API key is not authorized for this action. Missing scope: calls:write."
}

That last one is the scope check, and it applies to every endpoint except GET /v2/user/me and GET /v2/scopes. GET /v2/scopes lists each scope, the endpoints it gates and whether your key holds it.

1200 — not found

404. Scoped to your organization in every case.

{
  "error": 1200,
  "message": "Call not found."
}

{
  "error": 1200,
  "message": "Agent not found."
}

{
  "error": 1200,
  "message": "Campaign not found."
}

The recording route deliberately distinguishes two 404s that a client must handle differently: "Call not found." means no such execution in your organization, while "No recording is available for this execution." means the call is real but produced no audio — it was never answered, recording was disabled for it, or it has not finished yet.

{
  "error": 1200,
  "message": "No recording is available for this execution."
}

1201 — conflict

409. The resource exists and you may touch it, but not in its current state.

{
  "error": 1201,
  "message": "This call already ended (status=completed)."
}

{
  "error": 1201,
  "message": "The call is still being placed. Retry in a moment."
}

That second one is the moment between a call being accepted for dialling and its first status update arriving: the execution is real, it just has nothing to hang up yet. It carries Retry-After: 2. It is a 409 and not a 404 precisely because "retry in a moment" and "no such call" demand opposite client behaviour.

{
  "error": 1201,
  "message": "This campaign is completed and cannot be paused. A completed campaign never dials again; create a new campaign instead."
}

{
  "error": 1201,
  "message": "You cannot revoke the key you are authenticating with."
}

{
  "error": 1201,
  "message": "This workspace requires a passing test run before an agent goes live, and this agent has none. Run its tests in Evals, then try again."
}

That one answers "status": "ACTIVE" on POST /v2/agents or PATCH / PUT /v2/agents/{agent_id} where the workspace requires a passing test run before an agent goes live (Go-live check). The message says whether the agent has no test run, its latest run didn't pass, or a run is still going. Nothing in the request was saved: run the agent's tests, and send it again once the latest run passes.

1202 — agent switched off

409. The agent is switched off, so it takes no new calls. Nothing was dialled, queued or booked.

{
  "error": 1202,
  "message": "This agent is switched off, so it takes no new calls. Switch it on to call with it again."
}

You get it from POST /v2/calls, and when you start a campaign that calls with that agent — creating one with contacts, resume, revive, or moving a finished campaign's end_time later — with the message "This campaign's agent is switched off, so nothing can start calling. Switch the agent on, then try again." Switch the agent on and send the same request again.

Calls already in progress finish normally. A campaign that was calling when its agent was switched off pauses on its own: no contact is failed, no try is used up, retries and call-backs keep their place, and calls you scheduled wait. It picks up again within about a minute of the agent being switched on. Inbound calls to the agent's numbers are turned away while it is off, and web and in-app sessions with it do not start (a WebSocket session closes with code 4409).

1203 — agent deleted

409. The agent was deleted, so it takes no new calls. Nothing was dialled, queued or booked.

{
  "error": 1203,
  "message": "This agent was deleted, so it takes no new calls."
}

The same requests as 1202 return it. A campaign that was calling with the agent pauses and does not resume on its own: create a campaign with another agent to keep calling. Calls already in progress finish normally.

1204 — the number has had its calls for now

409. A workflow's Before a call is placed holds this agent's calls, and the number has already had as many calls as it allows in its window. Nothing was dialled. Retry-After says how many seconds until the person can be called again, and the message says when.

{
  "error": 1204,
  "message": "This number has had its calls for now: a workflow holds this agent's calls to it. It can be called again after 2026-11-03T20:32:25Z."
}

You rarely see it: POST /v2/calls queues a held call instead — 202, status: "scheduled", reason: "held_by_call_limit", placed at its scheduled_at — and answers 1204 only when it can't be queued. A call sent with scheduled_at is never refused: it waits, and is placed once the person can be called again.

1300 — rate limited

429. Two very different situations share this code; tell them apart by the message and by Retry-After.

Request rate. A per-organization sliding window, counted per group of endpoints:

{
  "error": 1300,
  "message": "Rate limit exceeded: 1200 requests per minute for this organization. Retry in 17s."
}

The window is 60 seconds. The figures are ceilings; a plan can raise them. Your own live figures are on GET /v2/user/me under rate_limits, and on every response's X-RateLimit-Limit.

Concurrency. Every line your organization may use is busy. An immediate POST /v2/calls is normally queued rather than refused: it answers 202 with status: "scheduled" and reason: "waiting_for_a_free_line", and dials the moment a line frees. You see this 429 only when the call cannot be queued:

{
  "error": 1300,
  "message": "Account concurrency limit reached (25 of 25 lines in use)."
}

This one carries Retry-After: 5. If the live limit cannot be read the message degrades to "Account concurrency limit reached; all lines are in use."

1400 — insufficient credits

402. The request was well-formed and authorized; the wallet cannot fund the call.

{
  "error": 1400,
  "message": "Insufficient credits to place this call."
}

It is returned once the account balance is zero or below. The balance can be negative: a call that has already connected is charged in full when it ends, whatever the balance. A request with scheduled_at is refused the same way, with the message "This account has insufficient credits to schedule a call. Add credits and schedule it again." Calls scheduled earlier are held until credits are added — see Call Lifecycle.

For a sub-account that uses its parent organization's credits, it is returned when the parent's balance is zero or below, or when the sub-account has reached its monthly limit; the message says which.

Web and in-app sessions don't start either: a WebSocket session closes with code 4402.

1500 — internal error

500. The message is a constant. Nothing about the failure reaches you.

{
  "error": 1500,
  "message": "An unexpected error occurred."
}

1501 / 1502 — temporarily unavailable, and timed out

503 and 504. A service the request depends on is temporarily unavailable (1501) or did not respond in time (1502). The message names which part of the platform it was — useful in a support ticket, not something to branch on:

{
  "error": 1501,
  "message": "Call storage is temporarily unavailable."
}

A 1502 reads the same way and ends "did not respond in time.". One 1501 carries a sentence of its own instead: "The signing secret could not be created. Retry shortly.".

Both are retryable with backoff. A 429 (error 1300) can also come from a part of the platform that is busy rather than from your own limits; it carries a Retry-After when one is known — honour it the same way.

Rate limit headers

Every /v2 response after your key is authenticated — success and failure — carries the same trio. A 401 comes before your organization is known, so it carries none:

X-RateLimit-Limit: 2000
X-RateLimit-Remaining: 1983
X-RateLimit-Reset: 41

X-RateLimit-Reset is seconds until the window rolls, not a timestamp. A 429 adds Retry-After, also in seconds.

Execution status

status on an Execution object. Sixteen values — the same statuses the dashboard's Call History shows, one-to-one.

Every Execution object also carries a boolean is_terminal, computed from the canonical status — use it and you never have to hard-code the set.

The three sets

Terminal — ten values. Nothing further will change the status:

completed, failed, busy, no-answer, canceled, stopped, error,
call-disconnected, balance-low, do_not_call

In-flight — the exact complement of terminal, six values. Keep polling:

queued, scheduled, rescheduled, initiated, ringing, in-progress

Failure — a strict subset of terminal, five values. These are the ones campaign retries act on:

failed, busy, no-answer, error, call-disconnected

Note what is not in the failure set: canceled, stopped, balance-low and do_not_call are terminal but are deliberately excluded, because a user-requested hangup, an empty wallet and a number on the do-not-call list are not conditions a redial would fix.

Spelling quirks, deliberately preserved

Two spellings are load-bearing and are not normalised away: changing either would break every integration that already matches on it.

Also: in-progress is hyphenated on an execution, and in_progress is underscored on a batch. no-answer is hyphenated on an execution; no_answer is underscored in a batch's per-contact accounting.

To make this survivable, the ?status= filter accepts the alternate spelling and normalises it on the way in. These aliases are accepted:

insufficient_credit is an older spelling of balance-low; calls recorded under either exist, so filtering on balance-low matches both.

Output is always the canonical value. One exception, stated plainly: an unrecognised stored value is returned to you as-is rather than being coerced into something that looks valid — the API will not invent a status.

voicemail is a filter, not a status

voicemail is not an execution status. A voicemail pickup is usually stored as no-answer plus a separate answered_by_voicemail flag — one recognised only after the call was recorded as connected stays completed with the flag set. ?status=voicemail filters on the flag, whatever the status, and ?status=completed,voicemail matches either condition. voice_mail and voice-mail are accepted spellings of the same filter.

Because it is a dimension rather than a status, a voicemail pickup is counted in voicemail and again under its status — usually no_answer — in usage figures, so those fields do not sum to the total.

In-flight calls are visible by default

GET /v2/calls and GET /v2/agents/{agent_id}/executions apply no implicit terminal-only filter. A scheduled, queued or ringing call shows up while it is pending or live. Pass ?status= explicitly if you want only finished calls. A duplicate record merged into the call it duplicated is never listed, so one call appears once.

Polling for completion

Poll GET /v2/calls/{execution_id} and stop on is_terminal. The examples below also spell out the terminal set so you can see exactly what is being waited on, and they honour Retry-After on a 429.

A single fetch, for reference:

curl https://api.graine.ai/v2/calls/8f2a1c7e-5d34-4b19-9c60-1a7f0b2e4d88 \
  -H "Authorization: Bearer gat_your_api_key_here"

import time
import requests
 
BASE = "https://api.graine.ai/v2"
HEADERS = {"Authorization": "Bearer gat_your_api_key_here"}
 
TERMINAL = {
    "completed", "failed", "busy", "no-answer", "canceled",
    "stopped", "error", "call-disconnected", "balance-low",
}
FAILURE = {"failed", "busy", "no-answer", "error", "call-disconnected"}
 
# Accepted alternate spellings, normalised the way the API normalises them.
ALIASES = {
    "cancelled": "canceled",
    "in_progress": "in-progress",
    "no_answer": "no-answer",
    "call_disconnected": "call-disconnected",
    "balance_low": "balance-low",
    "insufficient_credit": "balance-low",
}
 
 
def normalise(status):
    if not status:
        return None
    lowered = status.strip().lower()
    return ALIASES.get(lowered, lowered)
 
 
def wait_for_call(execution_id, timeout=900, interval=5):
    """Poll until the execution is terminal. Returns the final Execution object."""
    deadline = time.time() + timeout
 
    while time.time() < deadline:
        response = requests.get(
            "{0}/calls/{1}".format(BASE, execution_id),
            headers=HEADERS,
            timeout=30,
        )
 
        if response.status_code == 429:
            # Always present on a 429, in seconds.
            time.sleep(int(response.headers.get("Retry-After", interval)))
            continue
 
        if response.status_code in (502, 503, 504):
            # 1501 / 1502 are temporary. Back off and retry.
            time.sleep(interval)
            continue
 
        if response.status_code >= 400:
            body = response.json()
            raise RuntimeError(
                "Graine error {0}: {1}".format(body["error"], body["message"])
            )
 
        call = response.json()
 
        # Prefer the server-computed flag; fall back to the set for older clients.
        if call.get("is_terminal") or normalise(call.get("status")) in TERMINAL:
            return call
 
        time.sleep(interval)
 
    raise TimeoutError(
        "Execution {0} did not finish within {1}s".format(execution_id, timeout)
    )
 
 
call = wait_for_call("8f2a1c7e-5d34-4b19-9c60-1a7f0b2e4d88")
status = normalise(call["status"])
 
print(status, call["duration_seconds"], call["cost"]["total"])
 
if status == "completed":
    print(call["summary"])
elif status in FAILURE:
    print("Not reached:", status)
else:
    # canceled / stopped / balance-low — terminal, but not a failure.
    print("Ended without a failure outcome:", status)

Batch status

status on a Batch object. These are batch-lifecycle values and are a different enum from execution status — read the spelling note above before comparing strings across the two.

Pausing, resuming and cancelling

A batch is paused, resumed and cancelled through its campaign — pause, resume and cancel — which carry the action to every batch in it. A campaign that has completed, expired, been cancelled or been archived answers 409:

{
  "error": 1201,
  "message": "This campaign is completed and cannot be resumed. A completed campaign never dials again; create a new campaign instead."
}

Per-call status inside a batch

GET /v2/calls?batch_id={batch_id} returns Execution objects — exactly the same shape and the same status enum as every other call, filtered to that batch. There is no separate per-call status vocabulary on the wire; use the execution table above.

In-flight calls are included by default here too, so a queued or ringing call in the batch is visible while it is live.

curl "https://api.graine.ai/v2/calls?batch_id=7d1f0a52-1a2b-4c3d-9e8f-0a1b2c3d4e5f&status=failed,busy,no-answer&page_size=100" \
  -H "Authorization: Bearer gat_your_api_key_here"

The counts object

A Batch object carries counts with exactly five integer counts:

{
  "batch_id": "7d1f0a52-1a2b-4c3d-9e8f-0a1b2c3d4e5f",
  "status": "calls_dispatched",
  "total_contacts": 500,
  "counts": {
    "pending": 12,
    "in_flight": 43,
    "completed": 380,
    "failed": 65,
    "total": 500
  }
}

These are outcome buckets over the batch's contacts, not a tally of execution statuses — a contact that was retried still counts once. Each contact's state maps into them as follows:

Handling errors well

• Branch on error, not on message. The integer is the contract; the sentence is for humans and may be reworded.
• Retry 429, 503 and 504. Honour Retry-After on a 429; use your own backoff for 503 and 504. Do not retry 400, 401, 403, 404, 409 or 422 — the same request will fail identically.
• 409 is sometimes retryable, sometimes not. "The call is still being placed. Retry in a moment." ships a Retry-After and means retry. "This call already ended" and "This campaign is completed" do not — go read the resource instead.
• Treat 402 as a stop signal. A dial will keep failing until the wallet is funded. Do not loop on it.
• Watch X-RateLimit-Remaining on successes, not just on 429s. It is on every authenticated response, so you can slow down before you are rejected.

Checking the API is up

GET https://api.graine.ai/v2/health answers whether this service can serve requests at all. No authentication — a monitor that needs a credential is a credential living in a third-party dashboard.

curl -s https://api.graine.ai/v2/health

{ "status": "ok", "checks": { … one entry per part of the service … } }

The body also carries a checks object with one boolean per dependency it tested.

Point an uptime check at it and treat the status code alone as the signal: 200 is healthy, anything else is not. The body is for a human reading the alert.