Skip to main content

Errors

The Quick Apps Backend reports problems in three ways, depending on how much of the request they break. This page covers what users see in each case, and how an administrator finds the cause in the logs. It is for platform engineers who support Quick Apps users. It assumes you know orchestration.

Three kinds of errors​

KindWhenWhat the user sees
Request failureThe turn can't complete: the model call fails, a service is down, or the app hits an internal errorAn error, with an explanation and an error reference, shown as an error rather than a reply
Initialization issuesSome tools or skills fail to load, but the request continues without themAn Initialization issues stage above a normal answer
Tool failureOne tool call fails during the loopUsually nothing directly; the tool's fallback decides what the model hears

Request failures​

The message​

The backend picks the most specific message it has:

  1. The failing component's own user message, shown as is.
  2. Advice for known causes, such as a content policy rejection ("please rephrase your message") or a full context window ("please shorten your messages").
  3. A message for the status: authentication, permission, not found, payload size, rate limit, timeout, or connectivity. The wording says whether the AI model or a service failed.
  4. A model failure while answering, reported as such.
  5. Quick Apps' own conditions, such as the iteration limit or a missing Toolset.
  6. A generic message: "Something went wrong with the execution of your request. Please contact your administrator."

Transient causes, such as rate limits, timeouts, and outages, end with "Please try again later." Others carry advice that can help, such as contacting an administrator.

The error reference​

Every request failure carries a short reference, as in <message> (error reference: a1b2c3d4). The same reference is in one log record, with the stack trace, the internal details, and whether the error is retryable. To diagnose a failure, search the backend logs for the reference the user reports. Internal details appear only in the logs.

How the error is delivered​

The error is sent through the DIAL error protocol, not as chat text:

  • DIAL Chat shows an error box, not an assistant reply, and the user can regenerate the turn.
  • The error text isn't added to the conversation, so the model doesn't see it on later turns.
  • Text streamed before the failure stays visible, with the error below it.
  • Stages still open are closed as failed.

A failure before the stream opens returns a non-200 response with an OpenAI-style error body. A failure after it opens ends the stream with an error chunk.

Status codes​

The backend never returns 429, 502, 503, or 504. DIAL Core would retry those, and for an application it can't, so it would replace the explanation with a generic error.

  • Errors caused by the request keep their status: bad request, authentication, permission, not found, payload too large, validation.
  • Everything else, such as upstream rate limits, outages, timeouts, and internal errors, is returned as 500.
  • The real cause stays in the error's code, so a 500 can carry code: "429". API clients should classify errors by code, not by status.

Initialization issues​

When tools or skills fail to load, the request continues without them, and an Initialization issues stage lists each problem by feature. Typical causes are an invalid manifest part, an inaccessible Toolset or skill, and a name collision.

  • The stage closes as failed when a tool fails to load, or a whole skill source fails.
  • It closes as completed when only individual skills fail.

The stage is meant for the app's builder: it points at the part of the manifest to fix.

Invalid requests​

Before anything runs, the backend checks the shape of messages. A request that breaks it fails with 400, and the message lists every problem at once. See How a request is processed.

Further reading​