Errors

This guide describes what happens when a request to the Cannahub API fails. Every error is returned with an appropriate HTTP status code and a consistent JSON body, so you can branch on the status code first and use the machine-readable code for finer-grained handling.

The BFF (/api/*) normalizes both its own validation errors and errors bubbling up from the Medusa/Strapi backends into a single shape. Upstream statuses are preserved where it matters (for example a backend 429 stays a 429, and an upstream 5xx is surfaced as 502) so the client can react correctly instead of seeing everything as a generic 500.

Status codes

Check the HTTP status code first to know whether your request succeeded.

Error response shape

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "errors": {
        "email": ["Invalid email"]
      }
    }
  }
}

Error codes

Examples

400 — Validation error

Returned when the request body or query fails validation. When Zod validation is used, details.errors maps each invalid field to its messages.

curl -X POST https://api.cannahub.tech/api/whatsapp/link \
  -H "Authorization: Bearer {token}" \
  -H "Tenant-id: high-up" \
  -H "Content-Type: application/json" \
  -d '{ "email": "not-an-email" }'

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "errors": {
        "customerId": ["Required"],
        "email": ["Invalid email"],
        "token": ["Required"]
      }
    }
  }
}

401 — Unauthorized

The Bearer token is missing, invalid or expired.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Unauthorized"
  }
}

403 — Forbidden

The token is valid but the caller lacks permission — for example a member hitting an admin-only endpoint, or a request scoped to the wrong tenant.

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Forbidden"
  }
}

A plan limit being reached is also a 403, but uses the LIMIT_EXCEEDED code and includes usage in details:

{
  "error": {
    "code": "LIMIT_EXCEEDED",
    "message": "members limit exceeded",
    "details": {
      "current": 500,
      "limit": 500
    }
  }
}

404 — Not found

The resource does not exist (or was already consumed/deleted).

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Link code not found"
  }
}

409 — Conflict

The request conflicts with the current state of the resource, e.g. creating a resource that already exists. Conflicts forwarded from the backend keep the upstream message when available.

{
  "error": {
    "code": "CONFLICT",
    "message": "Member conflict"
  }
}

422 — Unprocessable entity

The payload is syntactically valid but semantically rejected by the backend.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "stocked_quantity must be greater than or equal to 0"
  }
}

429 — Too many requests

Rate limit reached. Back off and retry after a short delay. When the limit comes from an upstream backend it is forwarded with the SERVICE_UNAVAILABLE code and a 429 status.

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Too many requests to the backend, please retry shortly"
  }
}

500 / 502 / 504 — Server and upstream errors

500 is an unexpected failure inside the BFF. Failures originating in Medusa/Strapi are surfaced as 502 (BACKEND_ERROR), and upstream timeouts as 504 (SERVICE_UNAVAILABLE), so you can distinguish "our bug" from "the backend is down".

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Failed to fetch inventory items"
  }
}

Handling errors on the client

async function apiFetch<T>(path: string, init?: RequestInit): Promise<T> {
  const res = await fetch(`https://api.cannahub.tech${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${token}`,
      'Tenant-id': 'high-up',
      ...init?.headers,
    },
  })

  if (!res.ok) {
    const body = await res.json().catch(() => null)
    const code = body?.error?.code ?? 'UNKNOWN'
    const message = body?.error?.message ?? res.statusText

    if (res.status === 401) redirectToLogin()
    if (code === 'LIMIT_EXCEEDED') showUpgradePrompt(body.error.details)

    throw new ApiError(res.status, code, message, body?.error?.details)
  }

  return res.json()
}