Edit this page

API Handling server errors

You may pass different render options for server responses with an error code.

Any HTTP status code other than 2xx is considered an error code.

A common use case for this is form submissions, where a successful response should display a follow-up screen, but a failed response should re-render the form or display errors.

Rendering failed responses differently

To use a different render option for a failed server response, prefix the option with fail:

  url: '/action',
  method: 'post',
  target: '.content',   // when submission succeeds update '.content'
  failTarget: 'form',   // when submission fails update the form
  scroll: 'auto',       // when submission succeeds use default scroll behavior
  failScroll: '.errors' // when submission fails scroll to the error messages

When using Unpoly's HTML attributes with links or forms you may infix an attribute with fail:

<form method="post" action="/action"

Options that are used before the request is made (like { url, method, confirm }) do not have a fail-prefixed variant. Some options (like { history, fallback }) are used for both successful and failed responses, but may be overriden with a fail-prefixed variant (e.g. { history: true, failHistory: false }. Options related to layers, scrolling or focus are never shared.

Local content cannot fail

When the updated fragment content is not requested from a { url }, but rather passed as a HTML string, the update is always considered successful.

Ignoring HTTP error codes

The { fail } option or [up-fail] attribute changes how Unpoly determines whether a server response was successful. By default ({ fail: 'auto' }) any HTTP 2xx status code will be considered successful, and any other status code will be considered failed.

You may also pass { fail: false } or [up-fail=false] to always consider the response to be successful, even with a HTTP 4xx or 5xx status code.

Handling other types of failure

Fatal network errors

When a request encounters fatal error like a timeout or loss of network connectivity, Unpoly will emit up:request:fatal and not render.

Aborted requests

When a request was aborted, Unpoly will emit up:request:aborted and not render.

Unexpected content

A server might sometimes respond with unexpected content, like a maintenance page or a login form.

To handle these cases, see up:fragment:loaded.

This website uses cookies to improve usability and analyze traffic.
I accept or learn more