Error Handling
The shape of error responses and common status codes
Every error response has the same shape:
{
"error": {
"code": "BAD_REQUEST",
"message": "Either bank name or institutionId is required",
"details": null
}
}Status codes
| HTTP status | code | Meaning |
|---|---|---|
| 400 | BAD_REQUEST | The request was malformed (e.g. a required field is missing). |
| 400 | VALIDATION_ERROR | The request body failed schema validation — details contains field-level errors. |
| 401 | UNAUTHORIZED | No credentials were provided, or the API key/session is invalid, revoked, or expired. |
| 403 | FORBIDDEN | The credentials are valid, but not allowed to do this — e.g. an API key restricted to other services, or the organization has been suspended. |
| 404 | NOT_FOUND | The resource (verification record, plan, organization, etc.) doesn't exist or isn't visible to you. |
| 409 | CONFLICT | The request conflicts with existing state — e.g. re-confirming an already-verified billing transaction. |
| 502 | UPSTREAM_ERROR | An upstream provider (a bank, eTrade, afrocash) was unreachable or returned something unexpected. |
| 500 | INTERNAL_ERROR | An unexpected server error. |
A verification call succeeding (200 OK) is not the same as the verification result being
positive — check the status field in the response body (e.g. NOT_FOUND, REJECTED,
REQUIRES_REVIEW) rather than relying on the HTTP status code alone.
Organization suspension
If an organization is suspended by a platform administrator, every request scoped to that
organization returns 403 FORBIDDEN with a message explaining why, until it's reactivated. This
never happens automatically — only a superadmin action triggers it.