API Errors¶

All errors follow RFC 7807 Problem Details.

Error Types¶

/errors/not-found¶

Status: 404 Not Found

When: The requested resource does not exist.

Common causes: - Vehicle with specified make/model/year does not exist - Manufacturer slug is invalid or has no models

Resolution: Verify the resource identifier. Use /api/v1/makes/list to list valid manufacturers or /api/v1/vehicles/list to browse available vehicles.

Example:

{
  "type": "https://github.com/open-ev-data/open-ev-data-api/blob/main/docs/API_ERRORS.md#errorsnot-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "Vehicle not found with code: invalid:model:2024:unknown",
  "instance": "/api/v1/vehicles/code/invalid:model:2024:unknown"
}

/errors/bad-request¶

Status: 400 Bad Request

When: The request contains invalid parameters.

Common causes: - Search query is empty or too short (minimum 2 characters) - Invalid query parameter values or types

Resolution: Check the detail field for specific validation errors. Review the API documentation for parameter requirements.

Example:

{
  "type": "https://github.com/open-ev-data/open-ev-data-api/blob/main/docs/API_ERRORS.md#errorsbad-request",
  "title": "Invalid Request",
  "status": 400,
  "detail": "Search query must be at least 2 characters",
  "instance": "/api/v1/vehicles/search"
}

/errors/internal-error¶

Status: 500 Internal Server Error

When: An unexpected error occurred on the server.

Common causes: - Database connection failure - Unexpected server-side exception

Resolution: Retry the request. If the problem persists, report the issue with the instance URI.

Example:

{
  "type": "https://github.com/open-ev-data/open-ev-data-api/blob/main/docs/API_ERRORS.md#errorsinternal-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "Database query failed",
  "instance": "/api/v1/vehicles/list"
}

/errors/service-unavailable¶

Status: 503 Service Unavailable

When: The service is temporarily unavailable.

Common causes: - Database is offline or unreachable - Server is overloaded

Resolution: Wait and retry after a few seconds. Check service status if issue persists.

Example:

{
  "type": "https://github.com/open-ev-data/open-ev-data-api/blob/main/docs/API_ERRORS.md#errorsservice-unavailable",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "Database connection unavailable",
  "instance": "/api/v1/health"
}

Endpoints and Possible Errors¶