Core Concepts

​Errors

Scrub follows standard HTTP status codes. Application-level errors are identified by error_code and error_type in the response body — use these instead of HTTP status alone, similar to Plaid's error model.

​Error response format

{
  "error_code": "INVALID_BVN",
  "error_type": "INVALID_REQUEST",
  "message": "BVN must be exactly 11 digits",
  "request_id": "req_8f3k2m9x1p"
}
json

​Error codes

error_codeerror_typeHTTPmessage
INVALID_BVNINVALID_REQUEST400BVN must be exactly 11 digits
INVALID_NININVALID_REQUEST400NIN format or checksum invalid
CONSENT_REQUIREDINVALID_REQUEST403Customer consent reference missing or expired
UNAUTHORIZEDAUTHENTICATION401Invalid or missing Bearer token
ACCOUNT_NOT_FOUNDNOT_FOUND404Account not in Scrub network
REPORT_NOT_FOUNDNOT_FOUND404Credit report ID invalid or expired
RATE_LIMIT_EXCEEDEDRATE_LIMIT429Too many requests — check X-RateLimit-Reset
DUPLICATE_IDEMPOTENCYINVALID_REQUEST409Same key used with different payload
INSUFFICIENT_DATAINVALID_REQUEST422Not enough signals for fraud analysis
INTERNAL_ERRORINTERNAL500Unexpected server error — include request_id in support ticket

​HTTP status reference

StatusMeaning
200 OKRequest succeeded
201 CreatedResource created (fraud report, inquiry)
202 AcceptedAsync operation started (credit report)
400 Bad RequestMalformed or invalid input
401 UnauthorizedMissing or invalid authentication
403 ForbiddenConsent missing or insufficient permissions
404 Not FoundAccount, report, or resource not found
409 ConflictIdempotency key reused with different payload
422 Unprocessable EntityValid JSON but insufficient data for analysis
429 Too Many RequestsRate limit exceeded
500 Internal Server ErrorServer error — contact support with request_id

​Security

All traffic must use HTTPS (TLS 1.2+). Store API keys and webhook secrets securely. Never expose tokens on the client side.

IdempotencySupport