Guide

Errors

Status codes, the error body, and the cases that need handling in code.

The error body

A failed call returns a non-2xx status and an errors array. Quote the correlation_id if you contact us about a failure.

404
{
  "status": {
    "code": 404,
    "messages": []
  },
  "errors": [
    {
      "message": "Organisation not found",
      "code": ""
    }
  ],
  "correlation_id": "5f0c2a9e4b7d4c1e"
}

Status codes

StatusMeaningWhat to do
400The request was malformed, such as an invalid search chipFix the request. The message says what's wrong
401The token is missing, malformed or revokedCheck the Authorization header. See authentication
404No record has that reference, or the path doesn't existCheck the reference. Don't retry
422A parameter has a value outside its allowed listUse one of the values listed in the reference
429Too many requestsWait and retry with backoff. See limits
500Something failed on our side, or a malformed dateCheck dates are YYYY-MM-DD, then retry once. If it persists, contact us with the correlation_id

Known rough edges

  • An invalid date, such as 2026-02-30, returns a 500 with a database message instead of a 400. Validate dates before sending.
  • Some list filters quietly ignore a value they don't recognise and return the unfiltered list. Check the parameter reference for allowed values.
  • GET /v1/profiles/{profileReference}/ownership returns an empty array for an unknown reference, not a 404.

Handling errors in code

const res = await fetch("https://api.chikaraintel.com/v1/organisations/3f2a9c1e-7b4d-4e8a-9c21-5d6e7f8a9b01", {
  headers: { Authorization: `Bearer ${process.env.CHIKARA_API_TOKEN}` }
});

if (!res.ok) {
  const body = await res.json().catch(() => ({}));
  const message = body.errors?.map((e) => e.message).join("; ") || res.statusText;
  throw new Error(`${res.status}: ${message} (correlation ${body.correlation_id ?? "none"})`);
}

const { success } = await res.json();
console.log(success.name);

MCP tool errors

MCP tools report a refused call as a tool result with isError: true and a message the assistant can act on, such as Not found. or a condition that failed validation. Only a fault on our side surfaces as a JSON-RPC error. Each tool page lists the messages it returns.

Related