Error Handling
The IoT.live API uses structured response objects and standardised result values to communicate operational status, validation failures, permission issues, and asynchronous processing outcomes.
Proper error handling is essential for:
- Reliable integrations
- Operational automation
- Bulk workflow management
- Retry processing
- Troubleshooting and monitoring
[IMAGE PLACEHOLDER: API error handling workflow]
Error handling overview
The API may return:
- Successful responses
- Validation failures
- Authentication errors
- Permission errors
- Async processing states
- Partial operation results
Unlike some APIs, HTTP success alone does not guarantee operational success.
Integrations should always validate:
- The result field
- The responseMsg field
- Any operation-specific status information
Always validate the API result field instead of relying solely on HTTP response codes.
Standard response structure
Most API responses inherit from the shared ResponseAbstract object.
Example response:
Response fields:
Field | Description |
|---|---|
result | Operational result of the API request |
responseMsg | Descriptive message or error details |
corrId | Correlation ID matching the request |
responseTime | UTC timestamp |
version | API service version |
Common API result values
The API documentation defines multiple possible result values.
Success responses
Result | Description |
|---|---|
Success | Request completed successfully |
Pending | Request accepted and processing asynchronously |
Partially_Successful | Some operations succeeded while others failed |
Skipped | Requested operations were skipped |
Authentication and access errors
Result | Description |
|---|---|
Authentication_Failed | Invalid username or password |
User_Locked | User account locked |
Password_Expired | User password expired |
Captcha_Required | CAPTCHA verification required |
Invalid_MFA_Code | Submitted MFA code invalid |
MFA_Code_Expired | MFA code expired |
Not_Allowed | Insufficient permissions |
Contract and account errors
Result | Description |
|---|---|
No_Contract | Account lacks required service contract |
Contract_Expired | Service contract expired |
No_Explicit_Consent | User has not accepted required agreements |
Unverified | User email verification incomplete |
Operational and processing errors
Result | Description |
|---|---|
Failed | Request failed during execution |
Rejected | Request rejected, often due to rate violations |
Invalid_ClientId | Invalid temporary client identifier |
[IMAGE PLACEHOLDER: API result categories]
Example authentication failure
Example async processing response
Large operational workflows may initially return:
This means:
- The request was accepted
- Processing continues asynchronously
- Additional monitoring is required
Partial successes
Bulk operations may return:
Partially_Successful
This indicates:
- Some records completed successfully
- Some records failed
Common causes include:
- Invalid ICCIDs
- Provider restrictions
- Unsupported operations
- Subscription eligibility issues
- Temporary provider failures
Async and bulk operations should always be monitored until fully complete.
Validation and request formatting errors
Operational failures may also occur due to:
- Invalid JSON formatting
- Missing required fields
- Incorrect identifiers
- Unsupported values
- Invalid pagination parameters
Recommended handling includes:
- Request validation before submission
- Structured logging
- Safe retry handling
Retry handling
Retry strategies should distinguish between:
- Temporary failures
- Permanent validation errors
- Authentication failures
- Provider-side processing delays
Recommended retry candidates may include:
- Pending operations
- Temporary provider failures
- Rate limiting scenarios
Avoid automatic retries for:
- Invalid credentials
- Invalid request structures
- Unsupported operations
Rate limiting and rejected requests
The API may return:
Rejected
This may occur due to:
- API rate violations
- Excessive request volume
- Operational throttling
- Provider-side restrictions
Recommended mitigation includes:
- Exponential backoff
- Request batching
- Pagination
- Async workflows
[IMAGE PLACEHOLDER: Rate limiting workflow]
Logging recommendations
Recommended integration logging includes:
- corrId
- Request timestamps
- Result values
- Response messages
- Async operation IDs
- Failed record tracking
This improves:
- Troubleshooting
- Operational auditing
- Retry management
- Provider issue escalation
Async error monitoring
Async operations should be monitored using:
- Async status APIs
- Audit APIs
- Export APIs
- Campaign monitoring workflows
Monitor for:
- Failed records
- Partial successes
- Provider-side rejections
- Synchronisation delays
[IMAGE PLACEHOLDER: Async error monitoring dashboard]
Security considerations
Error responses may expose:
- Operational details
- Account state information
- Validation behaviour
- Processing workflows
Recommended practices include:
- Sanitising logs where appropriate
- Restricting error visibility
- Protecting exported error reports
- Avoiding sensitive credential exposure
Never log plaintext credentials in production integration logs.
Best practices
Recommended error handling practices include:
- Always validate result
- Handle async workflows correctly
- Monitor partial successes
- Use structured logging
- Retry transient failures carefully
- Validate requests before submission
- Track requests using corrId