Sandbox

Sandbox explainer with error simulation (zero-auth)

Sandbox mirror of POST /api/v1/explain. Zero-auth; shares the public-sandbox per-IP rate limit bucket (100 requests / hour). Resolves a structured Apier error_code into the same Explanation envelope production returns, with sandbox _meta (is_sandbox: true). ?simulate_error= forces a deterministic, locally synthesized error response (production-shaped body; no upstream is ever called) so SDK consumers and agent test harnesses can exercise the error contract without real failure conditions. POST body capped at 8192 bytes; an oversized body returns 413 REQUEST_TOO_LARGE naming the 8 KiB cap; empty or non-JSON bodies return 400 VALIDATION_FAILED. Unlike the public twin /api/v1/sandbox/public/explain, context.org_number accepts any 9-digit value (not gated to 999999999).

post/api/v1/sandbox/explain

Request

Base URL: https://www.apier.no
URL: https://www.apier.no/api/v1/sandbox/explain
Auth: none required

Query parameters

Force the sandbox to return a structured error response. tokens (Apier-edge failures) — missing_delegation → 403 AUTH_MISSING_DELEGATION; invalid_token → 401 AUTH_EXPIRED_TOKEN; validation_error → 400 VALIDATION_FAILED; scope_missing → 403 SCOPE_MISSING. upstream-failure tokens — altinn_timeout → 504 EXECUTION_DEADLINE_EXCEEDED (Altinn 3 instances endpoint timed out, response body carries the Altinn RFC 7807 envelope); invalid_certificate → 502 MASKINPORTEN_AUTH_FAILED (Maskinporten OAuth2 error_object — invalid_client); malformed_payload → 422 GOVERNMENT_VALIDATION_REJECTED (Skatteetaten validation errors with nested path[] arrays); upstream_5xx → 502 GOVERNMENT_UNAVAILABLE (generic government 5xx). The 500 INTERNAL_ERROR path is reserved for unexpected internal failures. Accepts BOTH lowercase public tokens (primary contract) AND uppercase internal explainer codes (back-compat). Wins precedence over reserved-org defaults.

Headers

X-Correlation-IDstring uuid

Optional request-scope UUID v4 that the client can set to thread its own trace across multiple requests. A valid UUID v4 is reused verbatim on the server; anything malformed or absent is replaced with a fresh crypto.randomUUID(). The canonical value is echoed back on the X-Correlation-ID response header AND persisted on every matching audit_log row — so a forensic query can reconstruct "every row from request X" without timestamp-based correlation. Accepted on every /api/v1/* operation via the proxy middleware; no per-operation opt-in required. The header is also emitted on every /api/v1/* response — see the X-Correlation-ID response-header component.

Request body

error_codestring required

A structured Apier error code from the Compliance Explainer registry (e.g. AUTH_MISSING_DELEGATION). Codes outside the registry return 400 VALIDATION_FAILED.

context_org_numberstring

Flat form of context.org_number: the organisation the error relates to (9 digits). Mixing flat context_* fields with the nested context object is rejected with 400 VALIDATION_FAILED.

context_scopestring

Flat form of context.scope: scope token interpolated into the bokmål explanation. Cannot be combined with the nested context object.

context_rolestring

Flat form of context.role: role code interpolated into the explanation. Cannot be combined with the nested context object.

context_fieldstring

Flat form of context.field: field name interpolated into the explanation. Cannot be combined with the nested context object.

context_upstream_systemstring

Flat form of context.upstream_system: upstream system name interpolated into the explanation. Cannot be combined with the nested context object.

Response

Explanation resolved. Same envelope shape as the public twin /api/v1/sandbox/public/explain.

successunknown required

Changes

No recorded changes to this operation across all 1 revision of this API.