Error codes

When Dotpane stops something a pane asked for, the pane gets a DashError. It has a name of "DashError", a code from the lists below, and a message written for people. Branch on code; the wording of message can change.

try {
  const res = await dash.fetch('https://api.github.com/user', {
    headers: { authorization: 'Bearer {{secrets.GITHUB_TOKEN}}' },
  });
  if (!res.ok) throw new Error('GitHub answered ' + res.status);
  show(await res.json());
} catch (err) {
  if (err.name === 'DashError' && err.code === 'PROXY_SECRET_NOT_BOUND') {
    showMessage('Connect a GitHub token in this pane’s settings.');
  } else {
    throw err;
  }
}

An error status from the API itself, such as 404 or 500, is not a DashError. The promise from dash.fetch resolves, with ok set to false.

dash.fetch and dash.storage reject their promise. dash.refresh, dash.on, dash.emit, dash.onProps and dash.onResize throw straight away when an argument is wrong, with VALIDATION_FAILED.

Errors from dash.fetch

Code	What it means	What to do
PROXY_URL_INVALID	The URL is not https, uses a port other than 443, has a user name or a password, names an IP address, is longer than 2,048 characters, contains a space, a control character or a backslash, or has a placeholder in its scheme or host.	Fix the URL. Encode spaces as %20.
PROXY_HOST_NOT_ALLOWED	The host is not in the manifest’s network.	Add it to network. On a canvas, the pane runs its last saved version, so save a version too.
PROXY_SECRET_UNKNOWN_SLOT	A placeholder names a slot the manifest does not declare, or something starts like a placeholder but is not one, for example {{secrets.token}} with a lower-case name.	Check the spelling, or add the slot under secrets in the manifest.
PROXY_SECRET_NOT_BOUND	The slot has no secret bound to it on this pane.	On the canvas, bind it in the pane’s settings. In the editor, bind it under Preview secrets.
PROXY_SECRET_HOST_MISMATCH	The host is missing from the slot’s hosts, or from the secret’s allowed hosts. A secret is only sent to a host both allow.	Add the host where it is missing: the slot in the manifest, or the secret on the Secrets page.
PROXY_BLOCKED_ADDRESS	The host resolves to a private, local or otherwise internal address.	Dotpane only calls public addresses. Use the API’s public hostname.
PROXY_DNS_FAILED	The host could not be resolved.	Check the hostname. If it is right, try again later.
PROXY_TIMEOUT	The API did not finish answering within 10 seconds.	Ask for less data, or keep answers with the cache option so fewer calls go out.
PROXY_RESPONSE_TOO_LARGE	The response is larger than 2 MB once decompressed.	Ask for less: a smaller page, fewer fields, a filter.
PROXY_REQUEST_TOO_LARGE	The body is larger than 256 KB, or the whole request is larger than 300 KB once encoded. Binary bodies fit up to about 220 KB.	Send a smaller body, or split it over several calls.
PROXY_UPSTREAM_ERROR	The connection to the API failed, for example with a TLS error, or it was refused or reset.	Check that the API is up and its certificate is valid. Try again later.
QUOTA_EXCEEDED	The account has made all its calls for this calendar month (UTC).	Wait for the next month. Calls answered from the cache count too, so the cache does not help here.
EGRESS_UNAVAILABLE	Dotpane could not reach the separate service that sends requests.	Try again shortly.
KMS_UNAVAILABLE	Dotpane could not decrypt a secret because the key service did not answer. Only calls with a placeholder can get this.	Try again shortly.

The first five codes are checked in the order shown, and the first failure stops the call. All five are checked before any secret is decrypted.

Errors from any call

Code	When	What to do
VALIDATION_FAILED	An argument is not valid. In the browser: a URL that is not a string, an unknown method, a body on GET or HEAD, cache outside 0 to 3,600 or on a method other than GET, a storage key that is empty or longer than 128 characters, a value or payload that cannot be turned into JSON, an event name longer than 64 characters, an event payload over 16 KB, a callback that is not a function. On the server: more than 30 headers or 8 KB of them, a placeholder in a header name, a secret with a line break used in a header, a storage value over 64 KB, or, in the preview, a draft manifest that is not valid.	Read message; it names the problem.
RATE_LIMITED	Too many calls. For dash.fetch: more than 60 a minute or 10 at once, for the account or for this pane. For dash.storage: more than 60 writes a minute, or 10 calls at once, for this pane. For any call: more than 200 messages a second from this pane. Dotpane also answers this way when it cannot check the limits for a moment, rather than letting calls through.	Make fewer calls: refresh less often, keep answers with cache, and wait before trying again.
LIMIT_REACHED	dash.storage.set would take the pane past 100 keys or 256 KB in all. Listening to more than 100 event names gives the same code, but dash.on does not throw; the refusal goes to the browser’s console.	Remove keys you no longer need with dash.storage.remove.
NOT_FOUND	The pane is no longer there, for example because it was removed from the canvas in another tab. dash.storage.get for a key that does not exist is not an error: it resolves with undefined.	Reload the page.
UNAUTHENTICATED	You are no longer signed in, for example because you signed out in another tab or the session ended.	Sign in again.
CSRF_REJECTED	The app’s request to Dotpane’s servers failed the check against cross-site requests. The app passes this check on its own, so a pane should not see it.	Reload the page.
INTERNAL	Something went wrong inside Dotpane, the app could not reach Dotpane’s servers, or it got a reply it could not read.	Try again. If it keeps happening, contact us.

Codes a pane does not see

These codes are part of the same list, so they appear in the types the editor knows. They come from the app’s own screens, not from dash calls.

Code	What it means
FORBIDDEN	Reserved. Dotpane does not return it at the moment: something that is not yours answers NOT_FOUND, as if it did not exist.
INVITE_REQUIRED	Sign-in only. Dotpane is invite-only, and the sign-in page says so when an address has no invite.
MAGIC_LINK_INVALID	Sign-in only. The emailed link expired or was already used; the sign-in page asks you to request a new one.
LAYOUT_CONFLICT	The canvas layout was changed somewhere else, such as in another tab. The canvas asks you to reload it.
LAYOUT_INVALID	A pane would overlap another, go past the edge of the grid, or break its manifest’s min or max size. Also when a pane you add does not fit.
PANE_IN_USE	You tried to delete a pane that is still on a canvas. Remove it from those canvases first; the app lists them.
SECRET_IN_USE	You tried to delete a secret that placed panes use. The app lists them and lets you delete it anyway. See Secrets.