Skip to main content

​
Error Response Format

All UIP API errors follow a consistent JSON structure: 
{
  "error": "The requested resource was not found",
  "code": "resource/not-found"
}
Best Practice: First check if the HTTP status code is not 2xx. Then examine the code field for specific details about what went wrong.

​
How to Handle Errors

1

Check HTTP Status Code

Verify if the response status code is in the 2xx range (success) or not.
2

Examine Error Code

If status is not 2xx, read the code field for specific error details.
3

Take Appropriate Action

Use the error code to determine how to handle the error (retry, show message, etc.).

​
HTTP Status Codes

UIP uses standard HTTP status codes:
Status CodeMeaningWhen It Occurs
200SuccessRequest completed successfully
400Bad RequestInvalid request parameters or format
401UnauthorizedInvalid or missing API key
403ForbiddenInsufficient permissions
404Not FoundResource doesn’t exist
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer-side issue
503Service UnavailableTemporary service disruption
Rate Limits: Currently, no rate limits are enforced on UIP APIs. However, rate limiting may be added in the future to ensure fair usage and system stability.

​
Error Codes Reference

​
Internal Errors

internal/server-error

HTTP 500 - An internal server error occurredCause:
  • Unexpected server-side issue
  • Database or service failure
  • Infrastructure problem
Solution:

​
Resource Errors

HTTP 404 - The requested resource was not foundCause:
  • Invalid session ID (Invalidate API)
  • Invalid audit reference ID (Audit API)
  • Resource was already completed or expired
  • Typo in resource identifier
Solution:
  • Verify the ID is correct
  • Check if session/audit record exists
  • Ensure resource hasn’t been invalidated or completed

​
Data Errors

HTTP 500 - The requested data is corrupted or invalidCause:
  • Data corruption on server side
  • Internal data integrity issue
  • Storage or database corruption
Solution:
  • Initiate a new request/session
  • Do not retry the same resource
  • Contact [email protected] if issue persists

​
Authentication Errors

HTTP 401 - Unauthorized access to the requested resourceCause:
  • Missing API key
  • Invalid credentials
  • Unauthenticated request
Solution:
  • Include API key in Authorization header
  • Verify credentials are correct
  • Check API key hasn’t expired
HTTP 403 - Insufficient permissions to access sensitive dataCause:
  • API key lacks required scope
  • Requesting restricted data fields (e.g., personal_number)
  • Account tier doesn’t support feature
Solution:
  • Check API key permissions in dashboard
  • Upgrade account for enterprise features
  • Request only data fields your account has access to
HTTP 401 - The provided API key is invalidCause:
  • API key is incorrect
  • API key format is malformed
  • Using wrong environment key
Solution:
  • Verify API key from dashboard
  • Check for typos or incorrect key format
  • Regenerate API key if needed
HTTP 401 - The API key has been revokedCause:
  • API key was manually revoked in dashboard
  • Security incident triggered automatic revocation
  • Key was deleted
Solution:
  • Generate new API key in dashboard
  • Update application with new key
  • Review security if unexpected revocation
HTTP 403 - The business has been archivedCause:
  • Business account was archived or suspended
  • Account closed
  • Compliance or billing issue
Solution:
  • Contact [email protected] to restore account
  • Resolve outstanding issues
  • Check account status in dashboard
HTTP 401 - API key is requiredCause:
  • No Authorization header provided
  • Empty API key value
  • Incorrect header format
Solution:
  • Include header: Authorization: Bearer YOUR_API_KEY
  • Verify header is being sent
  • Check for typos in header name

​
Request Errors

HTTP 400 - The request payload is invalid or missing required fieldsCause:
  • Missing required parameters
  • Invalid JSON format
  • Wrong parameter types
Solution:
  • Check API documentation for required fields
  • Validate JSON before sending
  • Verify parameter types match specification
HTTP 400 - The path parameter is invalid or missingCause:
  • Missing required path parameter
  • Empty path parameter value
  • Invalid path parameter format
Solution:
  • Verify path parameter is provided
  • Check path parameter is not empty
  • Ensure path parameter matches expected format
HTTP 400 - The uploaded file type is not allowedCause:
  • Unsupported file format (only PDFs are currently supported)
  • File extension doesn’t match content
  • Non-PDF file uploaded
Solution:
  • Convert file to PDF format
  • Ensure file has .pdf extension
  • Verify MIME type is application/pdf
HTTP 400 - The uploaded file size exceeds the limitCause:
  • File exceeds 20MB limit for attachments
  • PDF file is too large
Solution:
  • Compress PDF to reduce file size
  • Reduce image quality/resolution in PDF
  • Remove unnecessary pages or content
  • Maximum file size: 20MB (required for audit traceability)
HTTP 400 - The webhook URL is not accessibleCause:
  • Webhook URL is not responding
  • Firewall blocking UIP servers
  • Invalid webhook URL
Solution:
  • Verify webhook URL is accessible publicly
  • Check firewall rules
  • Test webhook with /webhook/test endpoint
  • Ensure HTTPS for production webhooks
HTTP 404 - No such registered route in API serviceCause:
  • Invalid API endpoint
  • Typo in URL path
  • Using deprecated endpoint
Solution:
  • Check API documentation for correct endpoint
  • Verify API version in URL
  • Remove trailing slashes
HTTP 400 - Additional data requestedCause:
  • Request requires additional information
  • Missing optional but recommended fields
Solution:
  • Review error message for required data
  • Add suggested fields to request

​
Payment Errors

HTTP 402 - Insufficient funds to complete the operationCause:
  • Account balance too low
  • Payment method declined
  • Billing issue
Solution:
  • Add funds to account
  • Update payment method in dashboard
  • Contact billing support

​
Best Practices

Check Status Code First

Always check HTTP status code before parsing error details. Non-2xx means an error occurred.

Use Specific Error Codes

Don’t just check for 400 or 500. Use the code field for specific handling.

Implement Retry Logic

Retry server errors (5xx) with exponential backoff. Don’t retry 4xx errors (client errors).

Don't Retry 4xx Errors

Client errors won’t succeed on retry. Fix the request instead.

Monitor Error Rates

Track error rates by code to identify integration issues early.

Log Error Details

Always log error code and message for debugging purposes.

​
Next Steps

Getting Started

Build your first integration with proper error handling

QR Integration

Learn about session expiration and timeout handling

API Reference

Complete API documentation with all endpoints