Reference

Error Codes

The Decode Hash API uses standard HTTP status codes and returns consistent error objects to help you handle failures gracefully.

Error Response Format

All error responses follow a consistent format with an error object containing a machine-readable code and a human-readable message:

error.codestring

A machine-readable error code. Use this for programmatic error handling.

error.messagestring

A human-readable description of what went wrong. Useful for debugging.

error.retry_afternumberOptional

Seconds to wait before retrying. Only present on 429 rate limit responses.

Error Codes

400Bad Requestbad_request

The request body is malformed or missing required fields. Check that you are sending valid JSON with the required parameters.

Response400 Bad Request

{
  "error": {
    "code": "bad_request",
    "message": "Request body must contain a 'hash' field."
  }
}

401Unauthorizedinvalid_api_key

The API key provided in the X-API-Key header is invalid, expired, or missing. Verify your key in the Decode Hash Dashboard.

Response401 Unauthorized

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked."
  }
}

402Payment Requiredquota_exceeded

Your monthly lookup quota has been exhausted. Upgrade your plan or wait until your quota resets at the start of the next billing cycle.

Response402 Payment Required

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly lookup quota exceeded. Upgrade your plan for more lookups."
  }
}

404Not Foundhash_not_found

The hash does not match any known phone number in the Decode Hash database. This is expected for hashes that do not correspond to Kenyan mobile numbers.

Response404 Not Found

{
  "error": {
    "code": "hash_not_found",
    "message": "The provided hash does not match any known phone number."
  }
}

422Unprocessable Entityinvalid_hash

The hash parameter is not a valid SHA-256 hash. It must be a 64-character hexadecimal string.

Response422 Unprocessable Entity

{
  "error": {
    "code": "invalid_hash",
    "message": "Hash must be a 64-character hexadecimal string."
  }
}

429Too Many Requestsrate_limited

You have exceeded the rate limit for your plan. Implement exponential backoff and retry after the time indicated in the Retry-After header.

Response429 Too Many Requests

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Try again in 12 seconds.",
    "retry_after": 12
  }
}

500Internal Server Errorinternal_error

An unexpected error occurred on our servers. If this persists, contact support.

Response500 Internal Server Error

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred. Please try again later."
  }
}

Handling Errors

We recommend the following best practices for error handling:

Always check the HTTP status code before parsing the response body.
Use the error.code field for programmatic error handling (e.g., switch statements).
Implement exponential backoff for 429 responses, respecting the retry_after value.
For 402 errors, notify users and prompt them to upgrade their plan.
Log error.message for debugging but do not expose it to end users in production.
Treat 500 errors as transient - retry with backoff up to 3 times.