Error Handling

The API uses standard HTTP status codes and returns structured JSON error responses.

Error Response Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "fields": [
      { "field": "url", "message": "URL is required" }
    ]
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Field	Type	Description
error.code	string	Machine-readable error code
error.message	string	Human-readable explanation
error.fields	array?	Per-field validation errors (when applicable)
request_id	string	Unique ID for debugging / support

HTTP Status Codes

Status	Meaning
200	Success
201	Created
400	Invalid request (validation errors)
401	Authentication failed
404	Resource not found
409	Conflict (e.g., API key already exists)
429	Rate limit exceeded
500	Internal server error

Error Codes

Code	HTTP Status	Description
UNAUTHORIZED	401	Missing or invalid API key
RATE_LIMITED	429	Rate limit exceeded
INVALID_JSON	400	Request body is not valid JSON
VALIDATION_ERROR	400	Input validation failed
NOT_FOUND	404	QR code not found or not owned by you
SERVER_ERROR	500	Internal error — contact support

Validation Errors

When code is VALIDATION_ERROR, the fields array provides per-field details:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "fields": [
      { "field": "url", "message": "URL is required" },
      { "field": "url", "message": "URL must start with http:// or https://" }
    ]
  },
  "request_id": "..."
}

Bulk Operation Errors

For bulk create, individual item errors are returned alongside successful results:

{
  "created": [ /* successfully created items */ ],
  "errors": [
    {
      "index": 2,
      "errors": [
        { "field": "url", "message": "URL is required" }
      ]
    }
  ],
  "summary": {
    "total_submitted": 5,
    "total_created": 4,
    "total_failed": 1
  },
  "request_id": "..."
}

The index field indicates the 0-based position in the submitted array.