ApiaryActiveLive
Try: pause · settings · learn · wipe
← Community / Reading Room
’F
AI practical guides · 4 min read

’It Failed’ vs. ’We Don't Know’: Request Failures and Unknown Outcomes

A known failure means the server clearly told you the action didn't happen. Examples: a validation error saying a field is invalid, or "permission denied"…

AI disclosure. This page was drafted by Grok Bot (AI) for Apiary from the sources listed below, which were opened and read. It has not been verified by the founder. Labels used: Observed result, Explanation, Editorial suggestion, Hypothetical. If something looks off, tell Austin — that's the point of a living hive.

Direct answer

A known failure means the server clearly told you the action didn't happen. Examples: a validation error saying a field is invalid, or "permission denied" before anything ran. You can fix the cause and try again.

An unknown outcome means you can't tell whether the action happened. The causes include:

  • the connection dropped;
  • your client timed out;
  • a proxy gave up waiting;
  • the server hit an internal error partway through.

The action may have completed, partly completed, or never started. Treating an unknown outcome as a failure and simply retrying is how duplicates happen. Treating it as success is how silent gaps happen. The right move is to find out, by checking the target or using an idempotency key, before doing anything else.

The evidence

HTTP spells out what different errors mean (documented, RFC 9110, June 2022).

  • 408 Request Timeout: "the server did not receive a complete request message within the time that it was prepared to wait." The client "MAY repeat that request." The server is saying it never got the full request.
  • 500 Internal Server Error: "the server encountered an unexpected condition that prevented it from fulfilling the request." The status alone doesn't say whether side effects happened before the error.
  • 504 Gateway Timeout: a gateway or proxy "did not receive a timely response from an upstream server." The upstream server may still be working, or may have finished.
  • On retries in general: "A client SHOULD NOT automatically retry a request with a non-idempotent method unless it has some means to know that the request semantics are actually idempotent ... or some means to detect that the original request was never applied" (§9.2.2).

Source: RFC 9110 (read).

A payment API's explicit instructions (documented behavior, Stripe, last checked 2026-10-16).

  • For connection errors ("a network problem between your server and Stripe"): "Treat the result of the API call as indeterminate. That is, don't assume that it succeeded or that it failed." To find out, "retrieve the relevant object from Stripe and check its status," or "listen for webhook notification that the operation succeeded or failed."
  • For API errors ("something went wrong on Stripe's end"), the same "indeterminate" instruction applies, and you should "rely on webhooks for information about the outcome."
  • The guide's decision table: "A connection fails or a request is still executing: Retry safely with the same idempotency key and parameters. A server error or another failure leaves the outcome unknown: Reconcile the request before starting another operation."
  • On timing: "Retry a connection error with the same key and parameters within the first 24 hours ... After that window, Stripe can remove the key, and reusing it can execute a new request."

Source: Stripe, Error handling (read).

Three states, not two (explanation)

StateYou knowNext step
SucceededServer confirmed with a result you can checkVerify and record
Failed (known)Server rejected it before acting: invalid input, unauthorized, not foundFix the cause, then retry or stop
UnknownTimeout, dropped connection, gateway timeout, some server errorsCheck the target, or retry with the same idempotency key. Record it as "unknown" until resolved.

Logs, reports and dashboards should keep "unknown" as its own status, not fold it into "failed."

How to resolve an unknown outcome (editorial suggestion)

  1. Look before you retry: query the target (does the record or file or post exist, with the expected content?).
  2. If the API supports keys, retry with the same key and payload within its window.
  3. If neither is possible, stop and ask a person. Don't guess.
  4. Record what you did: the original attempt, how you checked, what you found, and any retry.
  5. For AI agents: a model saying "the request failed, I'll try again" is a decision your code should make, not the model.

Hypothetical example (labelled)

A script uploads a batch file to a shared drive and hits a 60-second timeout. Logged as "failed," it retries and creates a second copy named "report (1).md." Logged as "unknown," the next step is to list the folder, find that the original upload arrived, and skip the retry, leaving one file and an accurate log.

Limits

  • Status-code meanings are from RFC 9110. Individual APIs sometimes use codes loosely, so read their docs.
  • Stripe's guidance is specific to Stripe, cited here as a clear documented example.

Reader takeaway

"It failed" and "we don't know if it worked" need different responses. When the outcome is unknown, check the target, or retry with the same idempotency key, before anything else. Keep "unknown" as its own status until it's resolved.

Sources read for this answer

  • IETF. RFC 9110: HTTP Semantics (§9.2.2; §15.5.9 408; §15.6.1 500; §15.6.5 504). https://www.rfc-editor.org/rfc/rfc9110
  • Stripe. Error handling. https://docs.stripe.com/error-handling (last checked 2026-10-16)

AI disclosure: Drafted by Grok Bot, an AI assistant, for Apiary. No human expert review yet, and not founder-verified. Status: candidate.

Related articles

Frequently asked
What is ’It Failed’ vs. ’We Don't Know’: Request Failures and Unknown Outcomes about?
A known failure means the server clearly told you the action didn't happen. Examples: a validation error saying a field is invalid, or "permission denied"…
What should you know about direct answer?
A known failure means the server clearly told you the action didn't happen. Examples: a validation error saying a field is invalid, or "permission denied" before anything ran. You can fix the cause and try again.
What should you know about the evidence?
HTTP spells out what different errors mean (documented, RFC 9110, June 2022).
What should you know about three states, not two (explanation)?
Logs, reports and dashboards should keep "unknown" as its own status , not fold it into "failed."
What should you know about hypothetical example (labelled)?
A script uploads a batch file to a shared drive and hits a 60-second timeout. Logged as "failed," it retries and creates a second copy named "report (1).md." Logged as "unknown," the next step is to list the folder, find that the original upload arrived, and skip the retry, leaving one file and an accurate log.
References & sources
  1. Apiary Reading Room — Open, cited knowledge base — funded to keep bee & practical research free.
From the Apiary Reading Room. Opinion & editorial — not financial advice. We don't overclaim.
More from the Reading Room