Error Codes

Errors use standard HTTP status codes and a consistent JSON envelope:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Payload does not match the kpi widget schema",
    "details": ["`value` must be a number"]
  }
}

code is a stable UPPERCASE string. message is human-readable. details is optional — present only when there's per-field context to give (chiefly validation).

Codes

Status	Code	Meaning
400	`BAD_REQUEST`	Body isn't valid JSON, isn't an object, or `as_of` isn't a valid timestamp
401	`UNAUTHORIZED`	Missing, invalid, or expired API credentials
403	`FORBIDDEN`	The key lacks the required `model:action` permission
404	`NOT_FOUND`	The widget doesn't exist in your org
422	`VALIDATION_ERROR`	`data` failed the widget type's schema — see `details`
503	—	The auth service is unreachable; retry

Validation errors

A 422 lists every schema problem in details, so you can fix the whole payload in one pass:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Payload does not match the line widget schema",
    "details": [
      "series[0].name must be a string",
      "series[0].points[1].y must be a number"
    ]
  }
}

See Widget Types for each type's schema.