Constructor Detail

Method Detail

• category

   final Optional<BetaRefusalStopDetails.Category> category()

  The policy category that triggered the refusal.

  null when the refusal doesn't map to a named category.

• explanation

   final Optional<String> explanation()

  Human-readable explanation of the refusal.

  This text is not guaranteed to be stable. null when no explanation is available for the category.

• fallbackCreditToken

   final Optional<String> fallbackCreditToken()

  Opaque code that refunds the cache-miss cost when retrying this refused request on the fallback model. Pass it as fallback_credit_token on the retry request. Expires 5 minutes after the refusal.

  The retry is sent either with the same request body (system, messages, tools, and other render-shaping fields), or with the same body plus one appended assistant message whose content is the partial text (with any trailing whitespace stripped from the final text block) and paired server-tool blocks from this refusal — which also authorizes that appended turn as an assistant-prefill continuation on models that otherwise disallow prefill. A token minted mid-server-tool-loop whose partial content was continuable may only be redeemed the second way — if a same-body retry is rejected with a 400 saying the token must be redeemed by continuing the partial response, retry the second way instead. Either way: same workspace, same platform; a mismatch is a 400. Resending a token for an already-warm prefix is permitted but yields no additional credit.

  null when the refused model isn't eligible for a fallback credit.

• fallbackHasPrefillClaim

   final Optional<Boolean> fallbackHasPrefillClaim()

  Whether the accompanying fallback_credit_token may be redeemed with the appended-assistant retry form. Only set when fallback_credit_token is present.

  true: retry by resending the same request body plus one appended assistant message whose content is this response's content with any trailing whitespace stripped from the final text block and unpaired tool_use blocks omitted (the same appended-turn shape described on fallback_credit_token), with the token attached. false: retry by resending the original request body unchanged, with the token attached — the appended-assistant form is not available for this refusal (no continuable partial content, or the request uses output_format or a tool_choice that forces tool use). One exception: when the request used output_format or a forced tool_choice and the refusal arrived after server tools (including MCP connector tools) had already executed, the token may not be redeemable by either retry form; if the exact-body retry is then rejected with a 400 saying the token must be redeemed by continuing the partial response, discard the token and retry without it.

  Advisory: if an appended-assistant retry is rejected with a 400 despite true, fall back to resending the original request body with the token.

• recommendedModel

   final Optional<String> recommendedModel()

  The server's suggested retry target for this refusal. Populated when a fallback attempt could not be made (the fallback model's rate limit was exhausted, or it was overloaded); names the fallback model the caller can retry directly. Null otherwise.

• _type

   final JsonValue _type()

  Expected to always return the following:

  JsonValue.from("refusal")

  However, this method can be useful for debugging and logging (e.g. if the server responded with an unexpected value).

• _category

   final JsonField<BetaRefusalStopDetails.Category> _category()

  Returns the raw JSON value of category.

  Unlike category, this method doesn't throw if the JSON field has an unexpected type.

• _explanation

   final JsonField<String> _explanation()

  Returns the raw JSON value of explanation.

  Unlike explanation, this method doesn't throw if the JSON field has an unexpected type.

• _fallbackCreditToken

   final JsonField<String> _fallbackCreditToken()

  Returns the raw JSON value of fallbackCreditToken.

  Unlike fallbackCreditToken, this method doesn't throw if the JSON field has an unexpected type.

• _fallbackHasPrefillClaim

   final JsonField<Boolean> _fallbackHasPrefillClaim()

  Returns the raw JSON value of fallbackHasPrefillClaim.

  Unlike fallbackHasPrefillClaim, this method doesn't throw if the JSON field has an unexpected type.

• _recommendedModel

   final JsonField<String> _recommendedModel()

  Returns the raw JSON value of recommendedModel.

  Unlike recommendedModel, this method doesn't throw if the JSON field has an unexpected type.

• _additionalProperties

   final Map<String, JsonValue> _additionalProperties()

• toBuilder

   final BetaRefusalStopDetails.Builder toBuilder()

• validate

   final BetaRefusalStopDetails validate()

  Validates that the types of all values in this object match their expected types recursively.

  This method is not forwards compatible with new types from the API for existing fields.

• isValid

   final Boolean isValid()

• equals

   Boolean equals(Object other)

• hashCode

   Integer hashCode()

• toString

   String toString()

• builder

   final static BetaRefusalStopDetails.Builder builder()

  Returns a mutable builder for constructing an instance of BetaRefusalStopDetails.

  The following fields are required:

  .category()
  .explanation()
  .fallbackCreditToken()
  .fallbackHasPrefillClaim()
  .recommendedModel()