Skip to main content

​
Error Response Format

All errors follow a consistent format: 
{
  "errors": [
    {
      "code": "ERROR_CODE",
      "message": "Human-readable error message",
      "details": {
        "field": "Additional context"
      }
    }
  ]
}
​
errors
array
required
Array of error objects
​
code
string
required
Machine-readable error code
​
message
string
required
Human-readable error description
​
details
object
Additional context about the error

​
Error Codes

​
400 Bad Request

Invalid request data or parameters.
{
  "errors": [{
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "field": "vehicleIds",
      "issue": "Must be a non-empty array"
    }
  }]
}
Solution: Check the request body against the API specification.

​
401 Unauthorized

Invalid or missing API key.
{
  "errors": [{
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }]
}
Solution: Verify your API key is correct and included in the Authorization header.

​
403 Forbidden

Insufficient permissions for the requested operation.
{
  "errors": [{
    "code": "FORBIDDEN",
    "message": "Insufficient permissions",
    "details": {
      "required": ["inspections:write"],
      "available": ["inspections:read"]
    }
  }]
}
Solution: Request additional scopes from your administrator.

​
404 Not Found

The requested resource does not exist or you don’t have access to it.
{
  "errors": [{
    "code": "NOT_FOUND",
    "message": "Vehicle not found"
  }]
}
Solution: Verify the resource ID and your company’s access to it.

​
500 Internal Server Error

An unexpected error occurred on the server.
{
  "errors": [{
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  }]
}
Solution: Retry the request. If the issue persists, contact support.

​
Best Practices

Retry Logic

Implement exponential backoff for transient errors (500, 503)

Log Errors

Log error responses for debugging and monitoring

Validate Input

Validate data client-side before sending to reduce 400 errors

Handle Gracefully

Provide meaningful error messages to end users

​
Example Error Handling

try {
  const response = await client.post('/inspections', data);
  return response.data;
} catch (error) {
  if (error.response) {
    const { code, message } = error.response.data.errors[0];
    
    switch (code) {
      case 'VALIDATION_ERROR':
        console.error('Invalid data:', message);
        break;
      case 'UNAUTHORIZED':
        console.error('Invalid API key');
        break;
      default:
        console.error('API error:', message);
    }
  }
  throw error;
}