Error Reference

Every non-2xx response from the InvesTeam API carries the same JSON envelope, so your client handles all failures one way. This page is the full catalog: the envelope's fields, every status code, and which errors are worth retrying.

What does an InvesTeam error look like?¶

Every error is a single top-level error object with four fields:

json

{
  "error": {
    "code": "bad_request",
    "message": "Human, UI-safe reason — shown verbatim.",
    "request_id": "b6f0...",
    "retryable": false
  }
}

code is from a closed set: bad_request, unauthorized, forbidden, not_found, conflict, rate_limited, upstream_error, internal_error. Branch on this, not on the HTTP status text.
message is human-readable and safe to show a user verbatim. It never leaks internal topology — no service names, upstream codes, or paths.
request_id is an edge-minted correlation id, also returned as the X-Request-Id response header (the two always match).
retryable tells a well-behaved client whether to retry with back-off.

What do InvesTeam error codes mean?¶

Each status code maps to one code and one meaning:

Status	`code`	Meaning
`400`	`bad_request`	The request could not be understood — an empty or malformed body, or a missing `Idempotency-Key` on a submit. Invalid input is normalized to `400`; the API never returns a bare framework `422`.
`401`	`unauthorized`	Missing or invalid credentials — an absent, malformed, or unverifiable token or key.
`403`	`forbidden`	Authenticated but not permitted — a missing scope, or a programmatic principal attempting a key-management or board route.
`404`	`not_found`	The resource does not exist. On a downstream poll route this means "not ready yet — keep polling"; on `GET /api/v1/briefs/{id}` it is a genuine unknown-or-foreign id.
`409`	`conflict`	An idempotency-key reuse with a different body, or an optimistic-concurrency clash.
`429`	`rate_limited`	A per-key rate or daily-quota limit was hit. Carries a `Retry-After` header (integer seconds) when a back-off is known.
`502`	`upstream_error`	An upstream service is temporarily unavailable.

An internal_error (500) is the catch-all for an unexpected server fault; like upstream_error it is retryable.

What is `retryable` in an InvesTeam error?¶

retryable is the server telling you whether a retry can succeed. Client-caused errors — bad_request, unauthorized, forbidden, not_found, conflict — are retryable: false: fix the request, do not retry it unchanged. Transient server-side errors — upstream_error, internal_error, and rate_limited — are retryable: true: retry with exponential back-off, and on a 429 wait the advertised Retry-After first.

A 404 on a downstream poll is not a failure to retry away — it is the not-ready signal. Keep polling on the same cadence. See the async model.

What is `request_id` for?¶

request_id is your support handle. It is minted at the edge, returned in both the error body and the X-Request-Id header on every response (success and error), and it correlates to the internal logs where the full technical detail lives. Quote it in any support request — a client-supplied X-Request-Id is ignored, so the value you report is always the server's own.

Where next?¶

For throttling specifically, see Rate Limits & Quotas. For how enums and fields evolve without breaking you, see Versioning & Deprecation. Common failures are answered in the Developer FAQ.