Error Handling

Understanding Viax API errors and how to handle them

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 JSON

Common causes:

• Missing required fields
• Invalid data types
• Malformed JSON

401 · Unauthorized

Authentication failed or missing credentials

Common causes:

• Invalid email/password combination
• User account does not exist

403 · Forbidden

User lacks permission for the requested action

Common causes:

• Account is inactive or suspended
• Insufficient permissions for admin endpoints
• Driver not approved

404 · Not Found

Requested resource does not exist

Common causes:

• User ID not found
• Trip ID not found
• Endpoint URL is incorrect

Server Error Codes

500 · Internal Server Error

Unexpected server error

Action: Retry the request. If the error persists, contact support.

503 · Service Unavailable

Service temporarily unavailable

Action: 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