Errors

Errors return JSON with an error message. Where a client can reasonably do something different depending on why a call failed, the body also carries a machine-readable code — match on that, never on the message text.

Status codes

Status	Meaning	What to do
`400`	Malformed YAML or XML	Fix the input; the body says what failed
`401`	No credential, or an unrecognised one	Send `Authorization: Bearer stfv_…`
`403`	Key recognised but expired	Rotate and extend — see below
`415`	Unsupported `Content-Type`	Send `text/yaml` (or `application/xml` for `reverse`)
`422`	Engine could not process a well-formed request	Usually a model the compiler rejects
`429`	Rate limited	Wait `Retry-After` seconds
`500`	Server fault	Retry; if it persists, tell us
`503`	Auth backend unavailable	Retry — your key is fine

`401` — authentication required

{
  "error": "Authentication required. Provide a valid API key.",
  "code": "auth_required",
  "hint": "Include header: Authorization: Bearer stfv_YOUR_KEY",
  "docs": "/api-docs.html"
}

On endpoints the web editor also uses, the same code comes with a sign-in URL instead of a key hint, so a browser client can render the right affordance.

`403` — `key_expired`

The key exists and belongs to you; it has passed its 30-day window.

{
  "code": "key_expired",
  "error": "API key expired on 2026-03-01T09:00:00.000Z.",
  "hint": "Rotate your key at https://opcua-modeler.sterfive.io/app/settings/api"
}

Distinct from 401 on purpose: the fix is a rotation, not a signup. See Authentication and API keys.

`429` — rate limited

Carries Retry-After and the X-RateLimit-* headers. Two different limits can produce it — the 30/minute burst limit or a daily quota — and the headers tell you which. See Quotas and rate limits.

`503` — not your fault

{ "error": "Authentication service temporarily unavailable. Please retry." }

Returned when the authentication backend cannot be reached. It is deliberately not reported as a 401: masking an outage as a credential problem sends you off regenerating a key that was never the issue. Retry with backoff.

Validation results are not errors

A model with problems still returns 200. The response reports valid: false with diagnostics — severity, code, message and line number. Reserve your error handling for the statuses above, and read valid for the modelling verdict.

curl -X POST https://api.opcua-modeler.sterfive.io/api/v1/validate \
  -H "Content-Type: text/yaml" \
  --data-binary @model.yaml

Diagnostic codes themselves are documented with the DSL — start at Conformance flags, which covers how severities are assigned and how to silence individual codes.

Status codes​

401 — authentication required​

403 — key_expired​

429 — rate limited​

503 — not your fault​

Validation results are not errors​