Error Codes - Adhere by Smartcomply

The Adhere API uses standard HTTP status codes. Codes in the 2xx range indicate success; 4xx codes indicate a client error; 5xx codes indicate a server-side issue.

HTTP Status Codes

Code	Name	Description
`200`	OK	The request succeeded and data is returned in the response body.
`400`	Bad Request	The request was malformed — a required parameter is missing, the value is invalid, or the request body is not valid JSON.
`401`	Unauthenticated	The `x-access-token` header is missing or the key is invalid.
`403`	Forbidden	The API key is valid but does not have permission to access this endpoint.
`402`	Payment Required	Your wallet balance is too low to run the check, or no wallet is configured for the branch.
`404`	Not Found	The requested resource does not exist.
`409`	Conflict	The resource is already in the requested state — for example, a verification that has already been submitted.
`422`	Unprocessable Entity	The request was well-formed but the data failed validation (e.g., an ID number that doesn’t match the expected format).
`429`	Too Many Requests	A rate limit or a retry limit was exceeded. Back off and retry.
`500`	Internal Server Error	An unexpected error occurred on Smartcomply’s end.
`502`	Bad Gateway	A dependent upstream service is temporarily unavailable.
`503`	Service Unavailable	The API is temporarily offline for maintenance.
`504`	Gateway Timeout	The upstream service did not respond in time.

Error Response Format

All error responses follow this structure:

{
  "status": "failed",
  "data": [],
  "message": "A human-readable description of the error"
}

Common Error Scenarios

401 — Missing or invalid API key

Ensure the x-access-token header is present and contains a valid, active secret key. Keys can be regenerated from the Adhere dashboard under Settings → API Keys.

{
  "status": "failed",
  "message": "Authentication credentials were not provided."
}

400 — Missing required parameter

Check the request body against the endpoint’s parameter table. All required fields must be present and non-empty.

{
  "status": "failed",
  "data": [],
  "message": "This field is required."
}

400 — Record not found

The provided ID (BVN, NIN, etc.) could not be matched in the source database. Verify the number is correct and belongs to a real record.

{
  "status": "failed",
  "data": [],
  "message": "Sorry, your check cannot be processed at the moment. Please try again in a few minutes"
}

5xx — Server errors

These are rare and typically transient. Implement exponential back-off retry logic in your integration. If a 5xx error persists for more than a few minutes, contact support.

Retrying Requests

For 5xx errors and network timeouts, retry with exponential back-off:

Attempt	Wait before retry
1st retry	1 second
2nd retry	2 seconds
3rd retry	4 seconds

Do not retry other 4xx errors — they indicate a problem with the request itself that must be fixed before retrying. 429 is the exception: back off and retry it.

SDK Error Codes

Requests made by the Web, Android and iOS SDKs use a different response envelope from the rest of the API. It carries a machine-readable code and a request_id:

{
  "status": "error",
  "code": "SDK_CONFIG_NOT_FOUND",
  "message": "No active SDK configuration found for this client_id.",
  "data": { "client_id": "..." },
  "request_id": "req_a1b2c3d4e5f6"
}

Quote the request_id when contacting support — it identifies the exact request in our logs.

Code	HTTP	Cause	Fix
`INVALID_API_KEY`	`401`	The API key is missing, malformed, unknown, or the branch is not enabled for onboarding	Check your key under Settings → API Keys
`SDK_CONFIG_NOT_FOUND`	`404`	`clientId` does not match an active SDK Config	Copy the Client ID from Settings → Integrations → SDK Setup. Do not generate one per attempt
`VALIDATION_ERROR`	`400`	One or more request fields failed validation	Read `data.errors` for the failing field and reason
`INVALID_SESSION`	`401`	The session token is missing, malformed or expired (30-minute lifetime)	Start a new session. Your `apiKey` and `clientId` stay the same
`RETRY_LIMIT_EXCEEDED`	`429`	Three failed verification attempts on one session	The user must start again with a new session
`ALREADY_SUBMITTED`	`409`	This verification has already been submitted	Read the outcome from the webhook rather than resubmitting
`WALLET_NOT_FOUND`	`402`	No wallet is configured for the branch	Contact support
`INSUFFICIENT_BALANCE`	`402`	Wallet balance is below the cost of the check. `data.required_amount` holds the shortfall	Top up your wallet in the dashboard
`SUBMISSION_FAILED`	`500`	The verification could not be saved	Retry with back-off; if it persists, contact support
`INTERNAL_ERROR`	`500`	Unexpected server-side error	Retry with back-off; quote the `request_id` if it persists

​HTTP Status Codes

​Error Response Format

​Common Error Scenarios

​Retrying Requests

​SDK Error Codes

HTTP Status Codes

Error Response Format

Common Error Scenarios

Retrying Requests

SDK Error Codes