Comprehensive guide to understanding, handling, and debugging API errors with detailed error codes and troubleshooting strategies.
All API errors follow a consistent JSON structure to help you quickly identify and resolve issues:
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"details": {
"field": "order_id",
"issue": "Order ID is required"
}
},
"meta": {
"timestamp": "2024-01-15T10:30:00.000Z",
"requestId": "req_abc123def456",
"version": "v1"
}
}Always false for errors
Machine-readable error identifier
Human-readable error description
Object with specific error context
Unique identifier for support
ISO 8601 error timestamp
200OK
Request succeeded
201Created
Resource successfully created
204No Content
Request succeeded, no content returned
400Bad Request
Invalid request syntax or parameters
401Unauthorized
Missing or invalid authentication
403Forbidden
Insufficient permissions for resource
404Not Found
Requested resource does not exist
422Unprocessable Entity
Request validation failed (VALIDATION_ERROR)
429Too Many Requests
Rate limit exceeded
500Internal Server Error
Unexpected server error occurred
503Service Unavailable
Temporary maintenance or overload
UNAUTHORIZEDInvalid or expired API key
Verify your API key format (zl_live_* or zl_test_*) and check the Authorization header is correct.
FORBIDDENAPI key lacks required permissions
Your API key doesn't have access to this resource. Contact support to update permissions.
VALIDATION_ERRORRequest validation failed
One or more request parameters are invalid. Check the error.details object for specifics.
NOT_FOUNDRequested resource doesn't exist
The order, shipment, or product ID provided does not exist in your account.
RATE_LIMIT_EXCEEDEDToo many requests
You've exceeded your rate limit. Check X-RateLimit-* headers and implement exponential backoff.
BAD_REQUESTMalformed request
The request syntax is invalid. Check your JSON structure and required parameters.
RESOURCE_CONFLICTResource state conflict
The operation conflicts with the current state of the resource (e.g., duplicate order number).
INTERNAL_ERRORServer encountered an error
An unexpected error occurred. Contact support with the requestId from the error response.
const apiKey = 'zl_live_xxxxx';
try {
const response = await fetch(
'https://app.3plship.com/api/v1/orders',
{
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(orderData)
}
);
const result = await response.json();
if (!result.success) {
const { code, message, details } = result.error;
switch (code) {
case 'VALIDATION_ERROR':
console.error('Validation failed:', details);
break;
case 'RATE_LIMIT_EXCEEDED':
const retryAfter = response.headers
.get('X-RateLimit-Reset');
console.log(`Retry after: ${retryAfter}`);
break;
case 'UNAUTHORIZED':
console.error('Invalid API key');
break;
default:
console.error('API error:', message);
}
throw new Error(message);
}
return result.data;
} catch (error) {
console.error('Request failed:', error);
throw error;
}import requests
api_key = 'zl_live_xxxxx'
url = 'https://app.3plship.com/api/v1/orders'
try:
response = requests.post(
url,
headers={
'Authorization': f'Bearer {api_key}',
'Content-Type': 'application/json'
},
json=order_data
)
result = response.json()
if not result.get('success'):
error = result.get('error', {})
error_code = error.get('code')
if error_code == 'VALIDATION_ERROR':
details = error.get('details', {})
print(f"Validation error: {details}")
elif error_code == 'RATE_LIMIT_EXCEEDED':
reset_time = response.headers.get(
'X-RateLimit-Reset'
)
print(f"Rate limited until: {reset_time}")
elif error_code == 'UNAUTHORIZED':
print("Invalid API key")
else:
print(f"API error: {error.get('message')}")
raise Exception(error.get('message'))
return result.get('data')
except requests.exceptions.RequestException as e:
print(f"Request failed: {e}")
raiseOur support team is here to help you resolve API errors and integration issues.