Errors
Every ecosystem app returns errors in a single shape. Status codes follow HTTP semantics; body follows RFC 7807 Problem Details with RBS extensions.
Error envelope
json
{
"type": "https://developers.redbroomsoftware.com/errors/subscription-required",
"title": "Subscription required",
"status": 402,
"detail": "This endpoint requires the 'pro' tier or higher.",
"instance": "/api/deals/12345",
"code": "subscription.tier_required",
"correlationId": "cid_01HQXZ...",
"tenantId": "org_abc123"
}Fields:
code— machine-stable error code (e.g.,auth.token_expired,webhook.signature_invalid). Treat as stable contract.correlationId— propagates across apps; include in support tickets.tenantId— when applicable, the org the error belongs to.
Status code conventions
| Status | Used for |
|---|---|
| 400 | Malformed request (JSON parse, missing required field) |
| 401 | Missing/invalid auth (no token, expired token, bad signature) |
| 402 | Tier gating — the tenant's subscription doesn't include this feature |
| 403 | Authenticated but not authorized for this resource |
| 404 | Resource does not exist in the caller's scope |
| 409 | Conflict (duplicate slug, version mismatch) |
| 422 | Validation failure (well-formed but semantically invalid) |
| 429 | Rate limit — check Retry-After header |
| 500 | Server error — retry with backoff |
| 502 / 503 / 504 | Upstream dependency failure — retry with backoff |
Correlation IDs
Every request carries a correlation ID in the X-Correlation-Id header (generated if absent). The SDK propagates it across inter-app calls so a single consumer action can be traced through Camino → Colectiva → Constanza logs.
SDK helpers
ts
import { correlationId } from '@r-bsoftware/ecosystem-sdk'Gotchas
- Retry only on 5xx and 429. 4xx are client errors — retrying won't help and can cause amplification.
- 401 on webhooks is the signature check, not the API key. Double-check you're signing the raw body, not a re-serialized JSON.
- 429 respect
Retry-After. It is always present and always accurate. Ignoring it gets your key rate-gated further.
Source of truth
- Error code catalog:
@r-bsoftware/ecosystem-sdk→types.ts - Correlation propagation:
correlation.ts