Errors — Wahlu API Docs

Error response format

Every JSON error uses the same strict envelope. The HTTP status and theerror.status value match, while request_id gives support a safe correlation identifier.

403 response

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This API key does not include the required scope.",
    "status": 403,
    "retryable": false,
    "request_id": "req_scope_01k0",
    "repair_guidance": "Use an API key with schedule:write.",
    "next_action": "use_authorized_api_key",
    "details": {
      "required_scopes": [
        "schedule:write"
      ]
    }
  }
}

Parameter	Type	Description
`success`*	false	Always false for an error response.
`error.code`*	string	Stable machine-readable error code.
`error.message`*	string	Safe human-readable explanation.
`error.status`*	integer	Canonical HTTP status, matching the response status.
`error.retryable`*	boolean	Whether retrying can succeed without changing the request.
`error.request_id`*	string	Correlation ID to include when contacting support.
`error.issues`	array	Optional bounded field-level validation issues.
`error.repair_guidance`	string	Optional safe guidance for repairing the request or state.
`error.next_action`	string	Optional bounded action identifier for an agent.

Common error codes

Parameter	Type	Description
`MALFORMED_REQUEST / INVALID_HEADER / INVALID_QUERY`	400	The request could not be interpreted or validated.
`UNAUTHORIZED`	401	The Bearer token is missing or invalid.
`INSUFFICIENT_SCOPE / BRAND_ACCESS_DENIED / ENTITLEMENT_REQUIRED`	403	The key lacks the required authority or product access.
`NOT_FOUND`	404	The resource is missing or not visible to this key.
`IDEMPOTENCY_KEY_CONFLICT`	409	The key was reused with different request data.
`DOMAIN_VALIDATION_FAILED / PREFLIGHT_BLOCKED`	422	The request is well formed but is not safe or ready to perform.
`RATE_LIMITED`	429	Wait for Retry-After before retrying.
`INTERNAL_ERROR / DEPENDENCY_UNAVAILABLE`	500 / 503	Retry only when retryable is true.

Handle errors safely

JavaScript

const response = await fetch("https://api.wahlu.com/v1/context", {
  headers: {
    Authorization: "Bearer wahlu_live_your_api_key_here",
  },
});

const body = await response.json();

if (!response.ok) {
  console.error(body.error.code, body.error.request_id);

  if (body.error.retryable) {
    const retryAfter = response.headers.get("Retry-After");
    // Retry after the server-provided delay. Do not retry non-retryable errors.
    console.log({ retryAfter, guidance: body.error.repair_guidance });
  }
}