Errors

How errors are returned

A failed request returns an HTTP status code and a flat JSON body. error is a stable code that your code can check. message explains the problem to a person.

{
  "error": "invalid_request",
  "message": "finn_id must be a valid UUID"
}

Some errors include extra fields:

Setup that happens on the website

Compliance, billing and API key management are done in the Finn dashboard, not through the API. When a request fails because one of them isn't done, the error includes action_url pointing at the page to finish it. Retry the request once that's done.

{
  "error": "compliance_required",
  "message": "Compliance approval is required. Complete the compliance application in the Finn dashboard (see action_url), then retry.",
  "action_url": "https://www.hirefinn.ai/dashboard/settings?tab=telephony-account"
}

Team members and roles are also managed only in the dashboard (Settings → Team). Show message and action_url to the person running your integration rather than retrying automatically. These errors don't go away until someone acts.

Responses don't include a request ID. If you contact support, include the method, path, time (UTC) and the full response body.

Status codes

A 404 for a resource you're sure exists usually means the API key belongs to a different organization.

Error codes

Every endpoint

Calls

Finns and voices

Deployments

Phone numbers

compliance_required returns 409 from the search endpoint and 403 from the rental endpoint. Check the error code, not the status.

Audiences

Errors outside the normal format

A few failures happen before your request reaches an endpoint, so their bodies use a different shape. Check the status code for these.

The body is parsed before the API key is checked. A body that isn't valid JSON gets 400 even when the key is missing or wrong, and it doesn't count toward your rate limits.

What to retry

There's no Idempotency-Key header. Retrying a write after an unclear result can do the work twice, for example placing two calls. api-idempotency shows how to check before you retry each write.

Client example

This client retries reads only. Writes go back to the caller so it can decide.

const BASE = "https://api.hirefinn.ai/api/v1";
const RETRYABLE = new Set([429, 500, 502]);

export async function finnGet(path: string, maxAttempts = 4): Promise<Response> {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const res = await fetch(`${BASE}${path}`, {
      headers: { Authorization: `Bearer ${process.env.FINN_API_KEY}` },
    });

    if (!RETRYABLE.has(res.status) || attempt === maxAttempts - 1) return res;

    const retryAfter = res.headers.get("Retry-After");
    const waitMs = retryAfter
      ? Number(retryAfter) * 1000
      : 2 ** attempt * 500 + Math.random() * 250;

    await new Promise((r) => setTimeout(r, waitMs));
  }
  throw new Error("unreachable");
}

import os, time, random, requests

BASE = "https://api.hirefinn.ai/api/v1"
RETRYABLE = {429, 500, 502}

def finn_get(path, max_attempts=4, **kwargs):
    headers = {"Authorization": f"Bearer {os.environ['FINN_API_KEY']}"}

    for attempt in range(max_attempts):
        res = requests.get(f"{BASE}{path}", headers=headers, timeout=30, **kwargs)

        if res.status_code not in RETRYABLE or attempt == max_attempts - 1:
            return res

        retry_after = res.headers.get("Retry-After")
        wait = float(retry_after) if retry_after else 2**attempt * 0.5 + random.random() * 0.25
        time.sleep(wait)

    raise RuntimeError("unreachable")

Failures that aren't HTTP errors

202 from POST /calls means Finn accepted the call and started dialing. It doesn't mean anyone answered. Calls can still fail after that: the line is busy, the carrier rejects the call, or nobody picks up. Those outcomes appear in the call record (GET /calls/{call_uuid}) and in the call.completed webhook. They never come back as an HTTP error.

So handle errors in two layers. An HTTP error means your request was wrong or Finn couldn't process it. A call outcome means the request worked but the call didn't go the way you wanted.

Reporting a problem

Send Finn support the method, path, time (UTC) and the full response body. Never include the API key. If the failure is intermittent, include the times of one failing request and one successful one.