API documentation

Errors

The Demarky API uses a consistent error envelope across all endpoints.

Error envelope

{
  "error": "error_code",
  "message": "Human-readable description",
  "request_id": "cce50960-a535-4472-a7a7-5b4f9719aa42",
  "details": {}
}

Field	Type	Description
`error`	string	Machine-readable error code
`message`	string	Human-readable description
`request_id`	string (uuid)	Correlation ID for debugging (always present on error responses)
`details`	object	Additional context (varies by error type)

Error codes

Status	Code	Description
400	`bad_request`	Malformed request syntax
401	`invalid_token`	Missing, invalid, expired, or revoked access token
403	`insufficient_scope`	Missing required scope
403	`account_suspended`	Account access is suspended
403	`quota_exceeded`	Account quota limit reached
404	`not_found`	Resource not found
409	`conflict`	Resource state conflict or idempotency conflict
413	`payload_too_large`	Request body exceeds 1 MB limit
422	`validation_error`	Request body or query validation failed
429	`rate_limit_exceeded`	Rate limit exceeded
500	`internal_error`	Unexpected server error
501	`not_implemented`	Feature not yet implemented

Validation errors

Validation errors include a details.issues array with per-field information:

{
  "error": "validation_error",
  "message": "Request body validation failed",
  "request_id": "cce50960-a535-4472-a7a7-5b4f9719aa42",
  "details": {
    "issues": [
      {
        "path": "product.price",
        "message": "Number must be greater than 0",
        "code": "too_small"
      }
    ]
  }
}

Rate limit errors

Rate limit errors include a retry_after_seconds value and a Retry-After header:

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests",
  "request_id": "cce50960-a535-4472-a7a7-5b4f9719aa42",
  "details": {
    "retry_after_seconds": 43
  }
}