Track Package
Track package delivery status using USPS tracking number. This endpoint provides real-time tracking information including delivery status, location updates, and estimated delivery times.
/API/v2/track.php
Cost: $0.01 per tracking number
Rate Limit: 60 requests per minute
Batch Limit: Maximum 35 tracking numbers per request
Supported Carriers: USPS
Tracking Number Requirements
- Minimum 5 characters per tracking number
- Valid USPS tracking number format
- Package must be in USPS system
- Optional customer reference and notes per tracking number
Authentication
This endpoint requires Bearer token authentication. Include your API key in the Authorization header.
curl -X POST https://developers.labelscheap.com/API/v2/track.php \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "X-Requested-With: XMLHttpRequest" \
-d '{"tracking": "9400176825477902024731"}'
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://developers.labelscheap.com/API/v2/track.php');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Authorization: Bearer YOUR_API_KEY',
'X-Requested-With: XMLHttpRequest'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'tracking' => '9400176825477902024731'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
import requests
headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY',
'X-Requested-With': 'XMLHttpRequest'
}
data = {
'tracking': '9400176825477902024731'
}
response = requests.post(
'https://developers.labelscheap.com/API/v2/track.php',
headers=headers,
json=data
)
data = response.json()
fetch('https://developers.labelscheap.com/API/v2/track.php', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY',
'X-Requested-With': 'XMLHttpRequest'
},
body: JSON.stringify({
tracking: '9400176825477902024731'
})
})
.then(response => response.json())
.then(data => console.log(data));
Request
This endpoint accepts a POST request with tracking information in the JSON body.
Headers
| Header | Required | Description |
|---|---|---|
Content-Type |
Yes | Must be application/json |
Authorization |
Yes | Bearer token with your API key |
X-Requested-With |
Yes | Must be XMLHttpRequest |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
tracking |
array | Yes | Array of tracking objects (max 35) |
tracking[].tracking_number |
string | Yes | USPS tracking number (minimum 5 characters) |
tracking[].customer_reference |
string | No | Optional reference number for your records |
tracking[].notes |
string | No | Optional notes about the tracking number |
Example Request Body
{
"tracking": [
{
"tracking_number": "9400176825477902024731",
"customer_reference": "ORDER-12345"
},
{
"tracking_number": "9400109699938860804872",
"customer_reference": "ORDER-12346",
"notes": "Priority Mail"
},
{
"tracking_number": "9400111899560654568397"
}
]
}
Response
The response includes detailed tracking information from USPS, including delivery status, location updates, and timestamps.
Success Response
{
"STATUS": "success",
"MESSAGE": "Tracking information retrieved successfully",
"CODE": "200",
"DATA": {
"tracking_results": [
{
"tracking_number": "9400176825477902024731",
"customer_reference": "ORDER-12345",
"tracking_data": {
"TrackInfo": {
"@attributes": {
"ID": "9400176825477902024731"
},
"TrackSummary": "Delivered, Front Door/Porch",
"TrackDetail": [
"Delivered, Front Door/Porch, January 15, 2024, 2:30 pm",
"Out for Delivery, January 15, 2024, 8:30 am",
// ... more tracking details ...
]
}
}
},
{
"tracking_number": "9400109699938860804872",
"customer_reference": "ORDER-12346",
"notes": "Priority Mail",
"tracking_data": {
"TrackInfo": {
"@attributes": {
"ID": "9400109699938860804872"
},
"TrackSummary": "In Transit to Next Facility",
"TrackDetail": [
"In Transit to Next Facility, January 15, 2024, 6:47 pm",
// ... more tracking details ...
]
}
}
}
],
"total_amount_deducted": 0.02,
"tracking_count": 2,
"success_count": 2
},
"TIMESTAMP": "2024-01-15 10:30:00"
}
Response Fields
| Field | Type | Description |
|---|---|---|
STATUS |
string | Always "success" for successful requests |
MESSAGE |
string | Human-readable success message |
CODE |
string | HTTP status code as string |
DATA.tracking_results |
array | Array of tracking results for each tracking number |
DATA.tracking_results[].tracking_number |
string | The tracking number that was queried |
DATA.tracking_results[].customer_reference |
string | Customer reference if provided in request |
DATA.tracking_results[].notes |
string | Notes if provided in request |
DATA.tracking_results[].tracking_data |
object | Complete tracking information from USPS |
DATA.total_amount_deducted |
number | Total amount deducted from account balance ($0.01 per tracking number) |
DATA.tracking_count |
number | Total number of tracking numbers in request |
DATA.success_count |
number | Number of successfully tracked packages |
TIMESTAMP |
string | ISO 8601 timestamp of the response |
Code Examples
Here are complete examples for different programming languages:
<?php
class LabelsCheapAPI {
private $apiKey;
private $baseUrl = 'https://developers.labelscheap.com/API/v2/';
public function __construct($apiKey) {
$this->apiKey = $apiKey;
}
public function trackPackages($trackingData) {
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $this->baseUrl . 'track.php');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Authorization: Bearer ' . $this->apiKey,
'X-Requested-With: XMLHttpRequest'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'tracking' => $trackingData
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($response === false) {
throw new Exception('cURL error: ' . curl_error($ch));
}
$data = json_decode($response, true);
if ($data === null) {
throw new Exception('Invalid JSON response');
}
return $data;
}
public function parseTrackingEvents($trackingData) {
$events = [];
if (isset($trackingData['DATA']['tracking_results'])) {
foreach ($trackingData['DATA']['tracking_results'] as $result) {
$trackingNumber = $result['tracking_number'];
$trackDetails = $result['tracking_data']['TrackInfo']['TrackDetail'] ?? [];
$events[$trackingNumber] = [];
foreach ($trackDetails as $detail) {
$parts = explode(', ', $detail);
if (count($parts) >= 2) {
$events[$trackingNumber][] = [
'status' => $parts[0],
'date' => $parts[1],
'time' => isset($parts[2]) ? $parts[2] : '',
'location' => isset($parts[3]) ? $parts[3] : ''
];
}
}
}
}
return $events;
}
}
// Usage
try {
$api = new LabelsCheapAPI('YOUR_API_KEY');
$trackingData = [
[
'tracking_number' => '9400176825477902024731',
'customer_reference' => 'ORDER-12345'
],
[
'tracking_number' => '9400109699938860804872',
'customer_reference' => 'ORDER-12346',
'notes' => 'Priority Mail'
]
];
$tracking = $api->trackPackages($trackingData);
if ($tracking['STATUS'] === 'success') {
echo "Total Amount Deducted: $" . $tracking['DATA']['total_amount_deducted'] . "\n";
echo "Tracking Count: " . $tracking['DATA']['tracking_count'] . "\n";
echo "Success Count: " . $tracking['DATA']['success_count'] . "\n\n";
$events = $api->parseTrackingEvents($tracking);
foreach ($events as $trackingNumber => $trackingEvents) {
echo "Tracking Number: " . $trackingNumber . "\n";
echo "Events:\n";
foreach ($trackingEvents as $event) {
echo "- {$event['status']} on {$event['date']} {$event['time']}";
if ($event['location']) {
echo " at {$event['location']}";
}
echo "\n";
}
echo "\n";
}
} else {
echo "Error: " . $tracking['MESSAGE'] . "\n";
}
} catch (Exception $e) {
echo "Error: " . $e->getMessage() . "\n";
}
?>
import requests
import json
from datetime import datetime
class LabelsCheapAPI:
def __init__(self, api_key):
self.api_key = api_key
self.base_url = 'https://developers.labelscheap.com/API/v2/'
self.headers = {
'Content-Type': 'application/json',
'Authorization': f'Bearer {api_key}',
'X-Requested-With': 'XMLHttpRequest'
}
def track_packages(self, tracking_data):
try:
response = requests.post(
f'{self.base_url}track.php',
headers=self.headers,
json={'tracking': tracking_data},
timeout=30
)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as e:
raise Exception(f'Request failed: {str(e)}')
except json.JSONDecodeError as e:
raise Exception(f'Invalid JSON response: {str(e)}')
def parse_tracking_events(self, tracking_data):
events = {}
if 'DATA' in tracking_data and 'tracking_results' in tracking_data['DATA']:
for result in tracking_data['DATA']['tracking_results']:
tracking_number = result['tracking_number']
track_details = result['tracking_data']['TrackInfo']['TrackDetail']
events[tracking_number] = []
for detail in track_details:
parts = detail.split(', ')
if len(parts) >= 2:
events[tracking_number].append({
'status': parts[0],
'date': parts[1],
'time': parts[2] if len(parts) > 2 else '',
'location': parts[3] if len(parts) > 3 else ''
})
return events
# Usage
try:
api = LabelsCheapAPI('YOUR_API_KEY')
tracking_data = [
[
'tracking_number' => '9400176825477902024731',
'customer_reference' => 'ORDER-12345'
],
[
'tracking_number' => '9400109699938860804872',
'customer_reference' => 'ORDER-12346',
'notes' => 'Priority Mail'
]
]
tracking = api.track_packages(tracking_data)
if tracking['STATUS'] == 'success':
print(f"Total Amount Deducted: ${tracking['DATA']['total_amount_deducted']}")
print(f"Tracking Count: {tracking['DATA']['tracking_count']}")
print(f"Success Count: {tracking['DATA']['success_count']}")
events = api.parse_tracking_events(tracking)
for tracking_number, tracking_events in events.items():
print(f"\nTracking Number: {tracking_number}")
print("Events:")
for event in tracking_events:
location_text = f" at {event['location']}" if event['location'] else ""
print(f"- {event['status']} on {event['date']} {event['time']}{location_text}")
else:
print(f"Error: {tracking['MESSAGE']}")
except Exception as e:
print(f"Error: {str(e)}")
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using System.Collections.Generic;
using Newtonsoft.Json;
public class TrackingEvent
{
public string Status { get; set; }
public string Date { get; set; }
public string Time { get; set; }
public string Location { get; set; }
}
public class LabelsCheapAPI
{
private readonly string _apiKey;
private readonly string _baseUrl = "https://developers.labelscheap.com/API/v2/";
private readonly HttpClient _httpClient;
public LabelsCheapAPI(string apiKey)
{
_apiKey = apiKey;
_httpClient = new HttpClient();
_httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");
_httpClient.DefaultRequestHeaders.Add("X-Requested-With", "XMLHttpRequest");
}
public async Task<dynamic> TrackPackagesAsync(List<dynamic> trackingData)
{
try
{
var requestData = new { tracking = trackingData };
var json = JsonConvert.SerializeObject(requestData);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await _httpClient.PostAsync($"{_baseUrl}track.php", content);
response.EnsureSuccessStatusCode();
var responseContent = await response.Content.ReadAsStringAsync();
return JsonConvert.DeserializeObject(responseContent);
}
catch (HttpRequestException ex)
{
throw new Exception($"Request failed: {ex.Message}");
}
catch (JsonException ex)
{
throw new Exception($"Invalid JSON response: {ex.Message}");
}
}
public Dictionary<string, List<TrackingEvent>> ParseTrackingEvents(dynamic trackingData)
{
var events = new Dictionary<string, List<TrackingEvent>>();
try
{
var trackResults = trackingData.DATA.tracking_results;
foreach (var result in trackResults)
{
var trackingNumber = result.tracking_number.ToString();
var trackDetails = result.tracking_data.TrackInfo.TrackDetail;
events[trackingNumber] = new List<TrackingEvent>();
foreach (var detail in trackDetails)
{
var detailString = detail.ToString();
var parts = detailString.Split(new[] { ", " }, StringSplitOptions.None);
if (parts.Length >= 2)
{
events[trackingNumber].Add(new TrackingEvent
{
Status = parts[0],
Date = parts[1],
Time = parts.Length > 2 ? parts[2] : "",
Location = parts.Length > 3 ? parts[3] : ""
});
}
}
}
}
catch
{
// Handle parsing errors gracefully
}
return events;
}
}
// Usage
public class Program
{
public static async Task Main()
{
try
{
var api = new LabelsCheapAPI("YOUR_API_KEY");
var trackingData = new List<dynamic> {
new { tracking_number = "9400176825477902024731", customer_reference = "ORDER-12345" },
new { tracking_number = "9400109699938860804872", customer_reference = "ORDER-12346", notes = "Priority Mail" }
};
var tracking = await api.TrackPackagesAsync(trackingData);
if (tracking.STATUS == "success")
{
Console.WriteLine($"Total Amount Deducted: ${tracking.DATA.total_amount_deducted}");
Console.WriteLine($"Tracking Count: {tracking.DATA.tracking_count}");
Console.WriteLine($"Success Count: {tracking.DATA.success_count}");
var events = api.ParseTrackingEvents(tracking);
foreach (var trackingNumber in events.Keys)
{
Console.WriteLine($"\nTracking Number: {trackingNumber}");
Console.WriteLine("Events:");
foreach (var evt in events[trackingNumber])
{
var locationText = !string.IsNullOrEmpty(evt.Location) ? $" at {evt.Location}" : "";
Console.WriteLine($"- {evt.Status} on {evt.Date} {evt.Time}{locationText}");
}
}
}
else
{
Console.WriteLine($"Error: {tracking.MESSAGE}");
}
}
catch (Exception ex)
{
Console.WriteLine($"Error: {ex.Message}");
}
}
}
Imports System
Imports System.Net.Http
Imports System.Text
Imports System.Threading.Tasks
Imports System.Collections.Generic
Imports Newtonsoft.Json
Public Class TrackingEvent
Public Property Status As String
Public Property Date As String
Public Property Time As String
Public Property Location As String
End Class
Public Class LabelsCheapAPI
Private ReadOnly _apiKey As String
Private ReadOnly _baseUrl As String = "https://developers.labelscheap.com/API/v2/"
Private ReadOnly _httpClient As HttpClient
Public Sub New(apiKey As String)
_apiKey = apiKey
_httpClient = New HttpClient()
_httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}")
_httpClient.DefaultRequestHeaders.Add("X-Requested-With", "XMLHttpRequest")
End Sub
Public Async Function TrackPackagesAsync(trackingData As List(Of Object)) As Task(Of Object)
Try
Dim requestData = New With {.tracking = trackingData}
Dim json = JsonConvert.SerializeObject(requestData)
Dim content As New StringContent(json, Encoding.UTF8, "application/json")
Dim response = Await _httpClient.PostAsync($"{_baseUrl}track.php", content)
response.EnsureSuccessStatusCode()
Dim responseContent = Await response.Content.ReadAsStringAsync()
Return JsonConvert.DeserializeObject(responseContent)
Catch ex As HttpRequestException
Throw New Exception($"Request failed: {ex.Message}")
Catch ex As JsonException
Throw New Exception($"Invalid JSON response: {ex.Message}")
End Try
End Function
Public Function ParseTrackingEvents(trackingData As Object) As Dictionary(Of String, List(Of TrackingEvent))
Dim events As New Dictionary(Of String, List(Of TrackingEvent))()
Try
Dim trackResults = trackingData.DATA.tracking_results
For Each result In trackResults
Dim trackingNumber = result.tracking_number.ToString()
Dim trackDetails = result.tracking_data.TrackInfo.TrackDetail
events(trackingNumber) = New List(Of TrackingEvent)()
For Each detail In trackDetails
Dim detailString = detail.ToString()
Dim parts = detailString.Split(New String() {", "}, StringSplitOptions.None)
If parts.Length >= 2 Then
events(trackingNumber).Add(New TrackingEvent With {
.Status = parts(0),
.Date = parts(1),
.Time = If(parts.Length > 2, parts(2), ""),
.Location = If(parts.Length > 3, parts(3), "")
})
End If
Next
Next
Catch
' Handle parsing errors gracefully
End Try
Return events
End Function
End Class
' Usage
Public Class Program
Public Shared Async Function Main() As Task
Try
Dim api As New LabelsCheapAPI("YOUR_API_KEY")
Dim trackingData = New List(Of Object) From {
New With {.tracking_number = "9400176825477902024731", .customer_reference = "ORDER-12345"},
New With {.tracking_number = "9400109699938860804872", .customer_reference = "ORDER-12346", .notes = "Priority Mail"}
}
Dim tracking = Await api.TrackPackagesAsync(trackingData)
If tracking.STATUS = "success" Then
Console.WriteLine($"Total Amount Deducted: ${tracking.DATA.total_amount_deducted}")
Console.WriteLine($"Tracking Count: {tracking.DATA.tracking_count}")
Console.WriteLine($"Success Count: {tracking.DATA.success_count}")
Dim events = api.ParseTrackingEvents(tracking)
For Each trackingNumber In events.Keys
Console.WriteLine($"\nTracking Number: {trackingNumber}")
Console.WriteLine("Events:")
For Each evt In events(trackingNumber)
Dim locationText = If(String.IsNullOrEmpty(evt.Location), "", $" at {evt.Location}")
Console.WriteLine($"- {evt.Status} on {evt.Date} {evt.Time}{locationText}")
Next
Next
Else
Console.WriteLine($"Error: {tracking.MESSAGE}")
End If
Catch ex As Exception
Console.WriteLine($"Error: {ex.Message}")
End Try
End Function
End Class
import React, { useState, useEffect } from 'react';
const TrackingComponent = () => {
const [trackingData, setTrackingData] = useState(null);
const [loading, setLoading] = useState(false);
const [error, setError] = useState(null);
const [trackingNumbers, setTrackingNumbers] = useState('');
const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://developers.labelscheap.com/API/v2/';
const trackPackages = async (trackingNumbers) => {
setLoading(true);
setError(null);
try {
const response = await fetch(`${BASE_URL}track.php`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${API_KEY}`,
'X-Requested-With': 'XMLHttpRequest'
},
body: JSON.stringify({
tracking: trackingNumbers.split(',').map(num => ({ tracking_number: num.trim() }))
})
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const data = await response.json();
setTrackingData(data);
} catch (err) {
setError(err.message);
} finally {
setLoading(false);
}
};
const parseTrackingEvents = (data) => {
const events = {};
if (data?.DATA?.tracking_results) {
data.DATA.tracking_results.forEach(result => {
const trackingNumber = result.tracking_number;
const trackDetails = result.tracking_data.TrackInfo.TrackDetail;
events[trackingNumber] = [];
trackDetails.forEach(detail => {
const parts = detail.split(', ');
if (parts.length >= 2) {
events[trackingNumber].push({
status: parts[0],
date: parts[1],
time: parts[2] || '',
location: parts[3] || ''
});
}
});
});
}
return events;
};
const handleSubmit = (e) => {
e.preventDefault();
if (trackingNumbers.trim()) {
trackPackages(trackingNumbers);
}
};
return (
<div>
<h3>Track Packages</h3>
<form onSubmit={handleSubmit}>
<input
type="text"
value={trackingNumbers}
onChange={(e) => setTrackingNumbers(e.target.value)}
placeholder="Enter tracking numbers separated by commas"
required
/>
<button type="submit" disabled={loading}>
{loading ? 'Tracking...' : 'Track Packages'}
</button>
</form>
{error && <div className="error">Error: {error}</div>}
{trackingData && trackingData.STATUS === 'success' && (
<div>
<h4>Tracking Information</h4>
<p>Total Amount Deducted: ${trackingData.DATA.total_amount_deducted}</p>
<p>Tracking Count: {trackingData.DATA.tracking_count}</p>
<p>Success Count: {trackingData.DATA.success_count}</p>
<h5>Tracking Events</h5>
<ul>
{Object.entries(parseTrackingEvents(trackingData)).map(([trackingNumber, events]) => (
<li key={trackingNumber}>
<strong>Tracking Number: {trackingNumber}</strong>
<ul>
{events.map((event, index) => (
<li key={`${trackingNumber}-${index}`}>
{event.status} on {event.date} {event.time}
{event.location && ` at ${event.location}`}
</li>
))}
</ul>
</li>
))}
</ul>
</div>
)}
</div>
);
};
export default TrackingComponent;
const axios = require('axios');
class LabelsCheapAPI {
constructor(apiKey) {
this.apiKey = apiKey;
this.baseUrl = 'https://developers.labelscheap.com/API/v2/';
this.headers = {
'Content-Type': 'application/json',
'Authorization': `Bearer ${apiKey}`,
'X-Requested-With': 'XMLHttpRequest'
};
}
async trackPackages(trackingNumbers) {
try {
const response = await axios.post(
`${this.baseUrl}track.php`,
{ tracking: trackingNumbers.split(',').map(num => ({ tracking_number: num.trim() })) },
{
headers: this.headers,
timeout: 30000
}
);
return response.data;
} catch (error) {
if (error.response) {
throw new Error(`HTTP ${error.response.status}: ${error.response.data?.MESSAGE || error.message}`);
} else if (error.request) {
throw new Error('No response received from server');
} else {
throw new Error(`Request failed: ${error.message}`);
}
}
}
parseTrackingEvents(trackingData) {
const events = {};
try {
const trackResults = trackingData.DATA?.tracking_results || [];
trackResults.forEach(result => {
const trackingNumber = result.tracking_number.toString();
const trackDetails = result.tracking_data.TrackInfo.TrackDetail;
events[trackingNumber] = [];
trackDetails.forEach(detail => {
const parts = detail.split(', ');
if (parts.length >= 2) {
events[trackingNumber].push({
status: parts[0],
date: parts[1],
time: parts[2] || '',
location: parts[3] || ''
});
}
});
});
} catch (error) {
console.error('Error parsing tracking events:', error);
}
return events;
}
}
// Usage
async function main() {
try {
const api = new LabelsCheapAPI('YOUR_API_KEY');
const trackingNumbers = '9400176825477902024731, 9400109699938860804872';
const tracking = await api.trackPackages(trackingNumbers);
if (tracking.STATUS === 'success') {
console.log(`Total Amount Deducted: $${tracking.DATA.total_amount_deducted}`);
console.log(`Tracking Count: ${tracking.DATA.tracking_count}`);
console.log(`Success Count: ${tracking.DATA.success_count}`);
const events = api.parseTrackingEvents(tracking);
console.log('\nTracking Events:');
Object.entries(events).forEach(([trackingNumber, trackingEvents]) => {
console.log(`\nTracking Number: ${trackingNumber}`);
console.log('Events:');
trackingEvents.forEach((event, index) => {
const locationText = event.location ? ` at ${event.location}` : '';
console.log(`- ${event.status} on ${event.date} ${event.time}${locationText}`);
});
});
} else {
console.log(`Error: ${tracking.MESSAGE}`);
}
} catch (error) {
console.error(`Error: ${error.message}`);
}
}
main();
Request Tester
Test the track package endpoint with your API key:
Common Error Responses
Here are the most common error responses you might encounter:
Invalid Batch Request (422)
{
"STATUS": "error",
"MESSAGE": "Validation failed",
"CODE": "422",
"DATA": {
"validation_errors": {
"tracking": "Maximum 35 tracking numbers allowed per request"
}
},
"TIMESTAMP": "2024-01-15 10:30:00"
}
Invalid Tracking Number Format (422)
{
"STATUS": "error",
"MESSAGE": "Validation failed",
"CODE": "422",
"DATA": {
"validation_errors": {
"tracking": {
"0": "Tracking number must be at least 5 characters"
}
}
},
"TIMESTAMP": "2024-01-15 10:30:00"
}
Insufficient Balance (402)
{
"STATUS": "error",
"MESSAGE": "Insufficient balance. Required: 0.03, Available: 0.01",
"CODE": "402",
"DATA": [],
"TIMESTAMP": "2024-01-15 10:30:00"
}
USPS API Unavailable (503)
{
"STATUS": "error",
"MESSAGE": "USPS API is currently unavailable",
"CODE": "5001",
"HTTP_STATUS": 503,
"DATA": {},
"TIMESTAMP": "2024-01-15 10:30:00"
}
Error Handling Best Practices
- Always validate tracking numbers before sending requests
- Handle rate limiting by implementing exponential backoff
- Implement retry logic for transient errors (5xx status codes)
- Check account balance before making tracking requests
- Display user-friendly error messages based on the error code
- Log error details for debugging and monitoring