Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.smartcomply.com/llms.txt

Use this file to discover all available pages before exploring further.

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

CodeNameDescription
200OKThe request succeeded and data is returned in the response body.
400Bad RequestThe request was malformed — a required parameter is missing, the value is invalid, or the request body is not valid JSON.
401UnauthenticatedThe x-access-token header is missing or the key is invalid.
403ForbiddenThe API key is valid but does not have permission to access this endpoint.
404Not FoundThe requested resource does not exist.
422Unprocessable EntityThe request was well-formed but the data failed validation (e.g., an ID number that doesn’t match the expected format).
500Internal Server ErrorAn unexpected error occurred on Smartcomply’s end.
502Bad GatewayA dependent upstream service is temporarily unavailable.
503Service UnavailableThe API is temporarily offline for maintenance.
504Gateway TimeoutThe 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

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."
}
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."
}
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"
}
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:
AttemptWait before retry
1st retry1 second
2nd retry2 seconds
3rd retry4 seconds
Do not retry 4xx errors — they indicate a problem with the request itself that must be fixed before retrying.