Error Handling

All API errors return a consistent JSON format.

Error Response Format

{
  "code": "error.error_type",
  "message": "Human-readable error message"
}

Validation errors include field details:

{
  "code": "error.validation",
  "message": "Validation failed",
  "details": [
    { "field": "licensePlate", "message": "License plate is required" }
  ]
}

HTTP Status Codes

Code	Description
200	Success
201	Created
204	No Content (successful delete)
400	Bad Request — Invalid parameters
401	Unauthorized — Missing or invalid API key
403	Forbidden — No access to resource
404	Not Found — Resource doesn't exist
429	Too Many Requests — Rate limit exceeded
500	Internal Server Error

Common Error Codes

Authentication

Code	Status	Description
error.unauthorized	401	Invalid or missing API key
error.forbidden	403	No permission to access resource

Validation

Code	Status	Description
error.validation	400	Request validation failed
error.bad_request	400	Invalid request format

Resources

Code	Status	Description
error.not_found	404	Resource not found
error.card_not_found	404	Card does not exist
error.project_not_found	404	Project does not exist

Card Operations

Code	Status	Description
error.card_already_active	400	Card is already activated
error.card_not_active	400	Card must be active

Rate Limiting

Code	Status	Description
error.rate_limit	429	Rate limit exceeded

Server

Code	Status	Description
error.internal_error	500	Unexpected server error