Errors

The public API uses HTTP status codes to signal coarse-grained outcomes (success, auth failure, validation error, server fault) and a consistent JSON error envelope to communicate the specifics. Implement the handler once and use it for every endpoint.

Status codes

Error envelope

Most non-2xx responses use this shape:

{
  "detail": {
    "error": "human-readable message"
  }
}

For example, an unknown api_key returns:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{ "detail": { "error": "invalid api_key" } }

A retrieve against a post that doesn't belong to your org:

HTTP/1.1 404 Not Found
Content-Type: application/json

{ "detail": { "error": "feedback post not found" } }

A 422 validation error returns FastAPI's structured error list — useful when several fields fail at once:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "api_key"],
      "msg": "Field required",
      "input": {}
    },
    {
      "type": "value_error",
      "loc": ["body", "limit"],
      "msg": "Input should be less than or equal to 100",
      "input": 250
    }
  ]
}

Why 404 instead of 403 for cross-org access

If you call POST /feedback-posts/retrieve with a post id that belongs to a different organization, ProductBridge returns 404 not found — not 403 forbidden. This is intentional:

• 403 would tell you "this resource exists, but you can't see it" — that's an information leak.
• 404 collapses "doesn't exist" and "exists in someone else's org" into the same response, so you can't enumerate cross-org resource ids.

For the same reason, the 401 envelope is identical regardless of why the key was rejected (missing / typo / revoked / wrong scope).

A recommended client-side handler

async function call(path, body) {
  const res = await fetch(`https://api.productbridge.io/api/external/v1${path}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });

  if (res.status === 200) {
    return res.json();
  }

  const errBody = await res.json().catch(() => ({}));

  switch (res.status) {
    case 401:
      throw new AuthError("Invalid or revoked api_key");
    case 404:
      throw new NotFoundError(errBody?.detail?.error || "not found");
    case 422:
      throw new ValidationError(errBody?.detail || []);
    case 400:
      throw new RequestError(errBody?.detail?.error || "bad request");
    default:
      if (res.status >= 500) throw new ServerError(`HTTP ${res.status}`);
      throw new Error(`Unexpected ${res.status}`);
  }
}

import httpx

class AuthError(Exception): ...
class NotFoundError(Exception): ...
class ValidationError(Exception): ...
class RequestError(Exception): ...
class ServerError(Exception): ...

def call(path: str, body: dict) -> dict:
    resp = httpx.post(
        f"https://api.productbridge.io/api/external/v1{path}",
        json=body,
    )
    if resp.status_code == 200:
        return resp.json()

    try:
        err = resp.json()
    except Exception:
        err = {}

    if resp.status_code == 401:
        raise AuthError("Invalid or revoked api_key")
    if resp.status_code == 404:
        raise NotFoundError(err.get("detail", {}).get("error", "not found"))
    if resp.status_code == 422:
        raise ValidationError(err.get("detail", []))
    if resp.status_code == 400:
        raise RequestError(err.get("detail", {}).get("error", "bad request"))
    if resp.status_code >= 500:
        raise ServerError(f"HTTP {resp.status_code}")
    raise Exception(f"Unexpected {resp.status_code}")

Retry guidance