Diagnostic Framework for API Integration
Integrating with the TG Validator API requires a deterministic approach to error handling. Because the service is synchronous—returning a single registration result for an E.164 formatted phone number—your application must be prepared to handle specific HTTP status codes and response envelopes (code, msg, data) to maintain service stability. Treating all non-200 responses as identical failures often leads to "validation debt," where downstream logic makes incorrect assumptions about a number's status.
Mapping Status Codes to Remediation
When an API request fails, the system provides both an HTTP status and a specific error code. Using these in tandem allows you to implement safe retry logic rather than treating all failures as generic errors.
- 401 (40100): Indicates a missing or invalid
X-API-Key. Verify your header configuration; if the key is rotated or invalid, generate a new one in the dashboard.
- 402 (40200): Insufficient balance. Check your account balance via the dashboard and recharge to proceed.
- 429 (42901): Concurrency limit exceeded. Your account has reached its limit of concurrent requests. Wait for existing requests to complete before retrying. These rejections do not trigger charges.
- 503 (50300): Service maintenance. Do not mark numbers as 'unregistered' during this state. Wait and retry; failed or undetermined checks are not charged.
- 504 (50400): Timeout. The request did not complete within the 30-second window. You may retry the request safely, as it will not be charged.
Preventing Validation Debt
Validation debt occurs when an application trusts a response without verifying the envelope. Every successful POST /api/v1/check request returns a JSON body containing id, identifier, registered, transaction_id, status, service_type, and charged_amount_micros.
Always validate the presence of the data.registered field before proceeding with business logic. It is critical to remember that a registered status is strictly an account-presence signal at the time of the check. It does not provide proof of identity, ownership, contact consent, or reachability. If you encounter persistent issues, use the developer dashboard to correlate API failures with your 7-day usage trends, and when contacting support, provide the transaction_id and the error response envelope while ensuring you exclude your X-API-Key and any sensitive credentials.
For further details on current limits and API specifications, consult the official documentation.
Diagnostic Framework for API Integration
Integrating with the TG Validator API requires a deterministic approach to error handling. Because the service is synchronous—returning a single registration result for an E.164 formatted phone number—your application must be prepared to handle specific HTTP status codes and response envelopes (
code,msg,data) to maintain service stability. Treating all non-200 responses as identical failures often leads to "validation debt," where downstream logic makes incorrect assumptions about a number's status.Mapping Status Codes to Remediation
When an API request fails, the system provides both an HTTP status and a specific error code. Using these in tandem allows you to implement safe retry logic rather than treating all failures as generic errors.
X-API-Key. Verify your header configuration; if the key is rotated or invalid, generate a new one in the dashboard.Preventing Validation Debt
Validation debt occurs when an application trusts a response without verifying the envelope. Every successful
POST /api/v1/checkrequest returns a JSON body containingid,identifier,registered,transaction_id,status,service_type, andcharged_amount_micros.Always validate the presence of the
data.registeredfield before proceeding with business logic. It is critical to remember that aregisteredstatus is strictly an account-presence signal at the time of the check. It does not provide proof of identity, ownership, contact consent, or reachability. If you encounter persistent issues, use the developer dashboard to correlate API failures with your 7-day usage trends, and when contacting support, provide thetransaction_idand the error response envelope while ensuring you exclude yourX-API-Keyand any sensitive credentials.For further details on current limits and API specifications, consult the official documentation.