Error reference

error is always present on a coded failure. detail is optional: some responses, such as {"error":"PROJECT_INVALID_KEY"} and {"error":"VALUE_REQUIRED"}, carry the code alone. A handler that reads body.error.code will read undefined on every error this API produces.

const res = await fetch("https://agentifys.ai/v1/credentials", {
  method: "PUT",
  headers: {
    Authorization: "Bearer era_your_project_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});

if (!res.ok) {
  const body = await res.json().catch(() => ({}));
  // The code IS body.error. POST /v1/chat is the one endpoint that answers a
  // bad key with {"detail":"Invalid API key"} and no error field — see below.
  const code = body.error || (res.status === 401 ? "PROJECT_INVALID_KEY" : "UNKNOWN");

  if (code === "RATE_LIMIT_EXCEEDED") {
    const wait = Number(res.headers.get("Retry-After") || 1);
    await new Promise((r) => setTimeout(r, wait * 1000));
    // retry once here
  } else if (code.startsWith("IDENTITY_")) {
    // re-sign the user_context server-side and retry
  } else {
    throw new Error(`${code}: ${body.detail || res.statusText}`);
  }
}

These surface on signed-mode features: private knowledge, the vault, per-user MCP OAuth, and scheduled tasks. The five IDENTITY_* codes all arrive as a 401 carrying the same detail, "This project requires a signed user_context.", so the error field is the only thing that tells them apart.

Rate limiting is on the moment a project is created, at 20 requests per minute and 500 per day. It is not opt-in; you turn it off or raise it in Settings. POST /v1/chat checks two separate buckets against those same numbers — one for the whole project, one keyed to the user id in the request — so a single user can exhaust the project window before their own.

Endpoints outside chat carry their own fixed limits, independent of the project setting:

Once POST /v1/chat has answered 200 and the stream is open, a failure cannot change the status code. It arrives instead as an SSE error event followed by data: [DONE]. The event carries a single content string:

data: {"type":"error","content":"PROJECT_NO_API_KEY"}

data: [DONE]

Only one value of content is a stable code you can switch on:

TOOL_UNAVAILABLE and TOOL_DISABLED are never HTTP statuses and never stream error events. They are the tool's own return value, delivered inside the result of a tool_end event. The request stays 200 and the turn keeps going. Decoded, the event looks like this:

{
  "type": "tool_end",
  "id": "call_1",
  "name": "lookup_order",
  "result": {
    "error": "TOOL_UNAVAILABLE",
    "message": "This tool is temporarily unavailable. Please try again later.",
    "detail": "HTTP 502 (attempt 4/4): upstream gateway"
  }
}

Both shapes carry a message written for the end user and a detail written for whoever has to fix it. The agent sees the whole object, so it can tell the user what happened and may try another path.