Errors

The ZB ID API uses conventional HTTP status codes and a consistent error response format to indicate success or failure. Every error response includes machine-readable codes and human-readable messages to help you diagnose issues quickly.

Error response format

All ZB ID API errors follow a consistent JSON structure. Every error response includes:

error - A machine-readable error code (e.g., UNAUTHORIZED, BAD_REQUEST)
message - A human-readable description of what went wrong
status - The HTTP status code as an integer
timestamp - An ISO 8601 timestamp indicating when the error occurred

This consistent format makes it straightforward to handle errors programmatically across all endpoints. The one exception is the UNAUTHORIZED response returned by the authentication filter (missing or invalid token), which carries error, message, and status but no timestamp.

Error response envelope

{
  "error": "BAD_REQUEST",
  "message": "Either an email or a phone number is required",
  "status": 400,
  "timestamp": "2026-07-10T10:15:30.123Z"
}

Authentication error

{
  "error": "INVALID_CREDENTIALS",
  "message": "Invalid credentials",
  "status": 401,
  "timestamp": "2026-07-10T10:16:45.456Z"
}

Error codes

The error field in each response maps to one of the following machine-readable error codes. Use these codes to implement specific handling logic in your application.

Name
UNAUTHORIZED
Type
401
Description
No access token was supplied, or the token is invalid, expired, or has been revoked. Returned by protected endpoints when authentication is required. This response carries only error, message, and status (no timestamp).
Name
INVALID_CREDENTIALS
Type
401
Description
The email or phone and password combination is incorrect, or a refresh token is invalid or expired.
Name
ACCOUNT_LOCKED
Type
403
Description
The account is locked (too many failed login attempts), suspended, or deactivated.
Name
FORBIDDEN
Type
403
Description
The token lacks the scope required for the requested action.
Name
BAD_REQUEST
Type
400
Description
The request is malformed, missing required fields, or contains invalid values.
Name
VALIDATION_ERROR
Type
400
Description
One or more request fields failed validation. The message lists each failing field and why.
Name
CONFLICT
Type
409
Description
The request conflicts with existing data (for example, registering an email or phone that already exists, or claiming an identifier owned by another account).
Name
RATE_LIMIT_EXCEEDED
Type
429
Description
Rate limit exceeded. Back off and retry later.
Name
INTERNAL_ERROR
Type
500
Description
An unexpected error occurred on the server. If this persists, contact support.

Handling tip: Check the error code first for programmatic branching, then use the message field for logging or displaying information to users.

Account locked example

{
  "error": "ACCOUNT_LOCKED",
  "message": "Account is locked",
  "status": 403,
  "timestamp": "2026-07-10T10:20:00.789Z"
}

Conflict example

{
  "error": "CONFLICT",
  "message": "Phone number already registered, log in with that phone instead",
  "status": 409,
  "timestamp": "2026-07-10T10:21:00.321Z"
}

Status codes

The ZB ID API uses standard HTTP status codes to indicate the outcome of requests.

Success codes

Name
200 OK
Description
Request succeeded. The response body contains the requested data or confirmation of the action.
Name
201 Created
Description
A new resource was successfully created (e.g., a new user account after registration).

Client error codes

Name
400 Bad Request
Description
The request body is invalid, missing required fields, or contains values that fail validation.
Name
401 Unauthorized
Description
Authentication failed. The access token is missing, malformed, or expired, or the login credentials are incorrect.
Name
403 Forbidden
Description
The authenticated user does not have the required permissions, or the account is locked.
Name
404 Not Found
Description
The requested user, client, or resource does not exist.
Name
409 Conflict
Description
The request conflicts with existing data (e.g., duplicate phone number during registration).
Name
429 Too Many Requests
Description
Rate limit exceeded. See the Rate Limiting page for details on limits and retry strategies.

Server error codes

Name
500 Internal Server Error
Description
An unexpected server-side error occurred. If this persists, contact the ZB ID support team.

Best practice: Always check the HTTP status code first, then parse the JSON error body for the error code and message to determine the specific failure reason.

Validation errors

When a 400 Bad Request error occurs due to invalid input, the response includes field-level details describing exactly which fields failed validation and why. This makes it easy to display specific feedback in your UI or logs.

Common validation failures

Missing required fields - A field that must be present was omitted from the request body
Invalid phone format - Phone numbers must follow the E.164 format (e.g., +263771234567)
Invalid field length - A string value is too short or too long
Invalid enum value - A field value does not match one of the allowed options

Error handling strategy

Check the HTTP status code (400 indicates a validation error)
Parse the message field for a summary of the issue
Display targeted feedback to the user based on the error details
Fix the invalid fields and retry the request

Validation error example

{
  "error": "VALIDATION_ERROR",
  "message": "phone: Invalid phone number format; password: Password is required",
  "status": 400,
  "timestamp": "2026-07-10T10:25:00.555Z"
}

Example error handling

Error handling

curl -s -X POST https://id.zb.co.zw/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "invalid-phone"
  }' | python3 -m json.tool