Skip to main content

​
Error Response Format

All API errors follow a consistent JSON structure: 
{
  "success": false,
  "message": "Human-readable error description",
  "error": "ERROR_CODE"
}
​
success
boolean
required
Always false for error responses
​
message
string
required
Human-readable error message in Spanish
​
error
string
Optional error code for programmatic handling

​
HTTP Status Codes

The Viax API uses standard HTTP status codes:

​
Success Codes

​
200
OK
Request succeeded. Response includes requested data.
​
201
Created
Resource successfully created (not commonly used)

​
Client Error Codes

​
400
Bad Request
Invalid request parameters or malformed JSONCommon causes:
  • Missing required fields
  • Invalid data types
  • Malformed JSON
​
401
Unauthorized
Authentication failed or missing credentialsCommon causes:
  • Invalid email/password combination
  • User account does not exist
​
403
Forbidden
User lacks permission for the requested actionCommon causes:
  • Account is inactive or suspended
  • Insufficient permissions for admin endpoints
  • Driver not approved
​
404
Not Found
Requested resource does not existCommon causes:
  • User ID not found
  • Trip ID not found
  • Endpoint URL is incorrect

​
Server Error Codes

​
500
Internal Server Error
Unexpected server errorAction: Retry the request. If the error persists, contact support.
​
503
Service Unavailable
Service temporarily unavailableAction: Wait and retry with exponential backoff.

​
Exception Types

The Viax client SDK defines the following exception types:

​
ServerException

Thrown when the server returns an error response (HTTP 400, 500, etc.). 
class ServerException extends AppException {
  const ServerException(String message);
}
Example: 
{
  "success": false,
  "message": "Email ya está registrado"
}

​
NetworkException

Thrown when there’s a network connectivity issue. 
class NetworkException extends AppException {
  const NetworkException(String message);
}
Common causes:
  • No internet connection
  • Request timeout
  • DNS resolution failure
  • Connection refused

​
NotFoundException

Thrown when a resource is not found (HTTP 404). 
class NotFoundException extends AppException {
  const NotFoundException(String message);
}
Example: 
{
  "success": false,
  "message": "Viaje no encontrado"
}

​
AuthException

Thrown for authentication failures (HTTP 401). 
class AuthException extends AppException {
  const AuthException(String message);
}
Example: 
{
  "success": false,
  "message": "Credenciales inválidas"
}

​
UnauthorizedException

Thrown for authorization failures (HTTP 403). 
class UnauthorizedException extends AppException {
  const UnauthorizedException(String message);
}

​
ValidationException

Thrown for data validation errors. 
class ValidationException extends AppException {
  const ValidationException(String message);
}

​
Common Error Scenarios

​
Invalid Credentials

{
  "success": false,
  "message": "Email o contraseña incorrectos"
}
Status Code: 401 Unauthorized

​
Email Already Registered

{
  "success": false,
  "message": "Email ya está registrado"
}
Status Code: 400 Bad Request

​
Missing Required Fields

{
  "success": false,
  "message": "Campo 'email' es requerido"
}
Status Code: 400 Bad Request

​
Trip Not Found

{
  "success": false,
  "message": "Viaje no encontrado"
}
Status Code: 404 Not Found

​
Driver Not Available

{
  "success": false,
  "message": "No hay conductores disponibles en esta área"
}
Status Code: 200 OK (success: false)

​
Network Timeout

{
  "success": false,
  "message": "Tiempo de espera agotado"
}
Client-side exception, no HTTP response received.

​
Error Handling Best Practices

1

Check HTTP Status

Always check the HTTP status code first to determine the error category
2

Parse Error Response

Parse the JSON error response to get the specific error message
3

Handle Gracefully

Display user-friendly error messages and provide actionable next steps
4

Log for Debugging

Log errors for debugging, but never expose sensitive information
5

Retry When Appropriate

Implement retry logic for network errors and 5xx server errors

​
Retry Strategy

For transient errors (network issues, 503 errors), implement exponential backoff: 
Future<T> retryWithBackoff<T>(
  Future<T> Function() operation, {
  int maxAttempts = 3,
  Duration initialDelay = const Duration(seconds: 1),
}) async {
  int attempt = 0;
  while (true) {
    try {
      return await operation();
    } catch (e) {
      attempt++;
      if (attempt >= maxAttempts || !shouldRetry(e)) {
        rethrow;
      }
      await Future.delayed(initialDelay * attempt);
    }
  }
}
Do not retry these errors:
  • 400 Bad Request
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found
Retry these errors:
  • Network timeouts
  • 500 Internal Server Error
  • 503 Service Unavailable

​
Timeout Configuration

The API has a default timeout of 30 seconds: 
static const Duration connectionTimeout = Duration(seconds: 30);
static const Duration receiveTimeout = Duration(seconds: 30);
Ensure your client implements appropriate timeout handling: 
try {
  final response = await client
    .post(url, body: data)
    .timeout(AppConfig.connectionTimeout);
} on TimeoutException {
  throw NetworkException('Tiempo de espera agotado');
}

​
Error Monitoring

The API includes error logging and crash reporting. Enable analytics in your configuration:
static const bool enableCrashReporting = true;

​
Support

If you encounter persistent errors or unexpected behavior:
  1. Check API status if monitoring is available
  2. Review the documentation for the specific endpoint
  3. Verify your request format matches the examples
  4. Contact technical support with:
    • Timestamp of the error
    • Request details (without sensitive data)
    • Full error response
    • Steps to reproduce

Build docs developers (and LLMs) love

Get started for freeTalk to us