Error codes
Every error code the API returns, what causes it, and what to do about it.
Every error.code the Lender API and Partner API can return, what triggers it, and how to handle it. Both APIs share this exact catalog.
Error catalog
| Code | Status | What it means |
|---|---|---|
unauthorized | 401 | The X-API-Key header was missing, malformed, unknown, or belongs to a revoked key. Check the key is present and current; revocation takes effect immediately, so a key removed in the Hub or portal fails here on the very next request. |
environment_mismatch | 403 | A live credential was used on sandbox.capvant.com, or a change was attempted on a live deal there. The sandbox host accepts sandbox keys and test deals only. Use api.capvant.com for live traffic. |
rate_limited | 429 | More than 120 requests in the current one-minute window, per key. The response carries a Retry-After header (seconds); back off until then rather than retrying immediately. Webhooks eliminate most of the polling that causes this. |
not_found | 404 | The path resolves to nothing your key can see: a reference/id that doesn't exist, or one that belongs to another organisation. Deliberately indistinguishable from "doesn't exist" so a key can never probe for another org's data. |
invalid_request | 400 | The body or query parameters failed validation: missing required field, wrong type, malformed JSON, or a value outside an enum. The message names the offending field where practical; fix the request and retry as-is. |
cap_exceeded | 422 | A per-account limit was hit. Today this is only POST /test/deals: at most 10 live sandbox deals at a time. Delete old ones with DELETE /test/deals/{ref} to make room, or wait until you no longer need them. |
internal_error | 500 | Something failed on our side. Safe to retry with backoff; if it persists across retries, contact your partnership manager with the timestamp and endpoint. |
Codes are stable identifiers for programmatic branching; message is for humans and its wording can change without notice.