The reasonCode field indicates the outcome of the query. Your integration should check this field to determine how to process the result.These reason codes are the same for every query. Always branch on reasonCode / numberStatus.Integrations should act on reasonCode. The description text is for people and may change. When an answer has no live HLR data, isLive is false and fallbackType shows which data it carries.
Successful Queries#
| Code | Description | isLive | Data |
|---|
000 | Successful query | true | Full HLR data available |
Partial Results (HTTP 200, usable data returned)#
| Code | Description | numberStatus | fallbackType |
|---|
100 | Subscriber error (temporary) | error | - |
101 | Unknown Subscriber | unknown | - |
102 | Absent Subscriber | absent | - |
103 | Teleservice not provisioned | not_provisioned | - |
104 | Roaming not allowed | roaming_blocked | - |
105 | Subscriber busy | busy | - |
106 | Subscriber blocked | blocked | - |
107 | Equipment error | equipment_error | - |
108 | Phone switched off | switched_off | - |
109 | Destination network error | network_error | - |
110 | Facility not supported | not_supported | - |
112 | No network response | no_response | - |
113 | Destination error | destination_error | - |
114 | No HLR coverage for destination network, or No coverage for this destination | no_coverage | - |
120 | Internal system error | undetermined | - |
141 | Remote error - no live HLR data | - | GNR |
200 | Remote failure - no live HLR data | - | GNR |
300 | Absent Subscriber - no live HLR data | absent | GNR |
301 | Unknown Subscriber - no live HLR data | unknown | GNR |
302 | Live Status unavailable - no live HLR data | - | GNR |
303 | Subscriber error - no live HLR data | error | GNR |
304 | Destination/Network error - no live HLR data | network_error | GNR |
305 | Call barred - no live HLR data | barred | GNR |
306 | Teleservice not provisioned - no live HLR data | not_provisioned | GNR |
307 | Facility not supported - no live HLR data | not_supported | GNR |
310 | Live query failed - no live HLR data | - | NPQ |
Code 120 is a normal result, not an HTTP error: a synchronous lookup returns HTTP 200, and an
async task completes with the result. The query reached the destination network, but the
network answered with an error that does not show the subscriber's state, so the number's
status cannot be determined from this answer. numberStatus is normally undetermined and
isLive is not true. It is charged like other network answers: queryCost shows the
amount. Do not retry straight away: the same number usually gets the same answer, and on some
networks every query is answered this way.Invalid and unallocated numbers (HTTP 200)#
These are definitive answers about the number. They are returned with HTTP 200 like any
other result, with numberValid set to false and, where known, validationError
saying why. Do not retry them: the answer will not change. The queryCost field of each
response is the amount actually charged.| Code | Description | Charged |
|---|
004 | Country code invalid | HLR: usually. MNP: no |
005 | Wrong number length or format | HLR: usually. MNP: only for the length case below |
006 | Range not allocated | yes |
007 | Number not found (onboard) | yes |
008 | Number not found (remote) | yes |
A number with more than 16 digits is answered with 005 straight away and is charged at
the rate of the service you called, on HLR and on MNP alike, provided that service is
sold for the number's destination. Any other 005 on MNP is not charged. A number with
2 to 6 digits is too short to identify a destination, and a number of any length to a
destination that is not sold is treated the same way: both are answered with 114 (no
coverage) and are not charged.Error Codes (HTTP 4xx/5xx)#
| Code | HTTP | Description |
|---|
001 | 400 | Invalid query format |
002 | 400 | Query service invalid |
003 | 403 | Service not allowed |
009 | 502 | Service error (retry recommended) |
012 | 403 | Customer not authorized |
013 | 429 | Rate limit reached |
HTTP 502 means no answer could be obtained. The body is {"detail": "Service temporarily unavailable"}. It carries no reasonCode and is not charged. An async task in this case ends as failed with the same error_message, and is not charged either. Safe to retry after a brief delay. Modified at 2026-11-04 07:05:05