Errors & Status Codes
Every failure returns JSON of the form { "error": "message" } with an appropriate HTTP status. There is no error code enum — match on the status, and log the message.
| Status | Meaning | Typical cause |
|---|---|---|
| 200 | OK | Successful read or update |
| 201 | Created | RFQ, quote, business, product or webhook created |
| 400 | Bad Request | Missing required field, or a path that does not start with /v1/ |
| 401 | Unauthorized | Missing header, unknown/inactive key, or expired key |
| 403 | Forbidden | Key lacks the named scope |
| 404 | Not Found | Unknown resource, unknown route, or a record hidden by visibility rules |
| 405 | Method Not Allowed | Wrong method on a search endpoint |
| 429 | Too Many Requests | Per-key rate limit tripped — back off |
| 500 | Internal Server Error | Unhandled error or a database error surfaced verbatim |
| 503 | Service Unavailable | Semantic search called without embeddings configured |
A 404 does not always mean "does not exist". Non-public businesses and non-active products are hidden as 404 for keys without the matching internal scope.
Best practices
- Check the status before parsing — error bodies do not contain
data. - Exponential backoff with jitter on 429 and 5xx; no retry on other 4xx.
- Validate payloads client-side; most 400s are a missing
title,buyer_name,items,supplier_id, orq. - Alert only after repeated 5xx — single failures are usually transient.
Current as of API 1.1.0 — released 7 September 2026