Errors and retries

The error shape

An error is JSON with a short code, one plain sentence, and the field it is about when it is about one:

{
  "code": "permission_denied",
  "message": "this connection does not hold that permission on this company"
}

Branch on the status and on code. Log message or show it to a person, and do not parse it.

Status codes

Every status the contract defines, read from the contract when these pages were built:

What to do with each

• 200: the read worked. If truncated is true, ask again for a narrower window. If window.narrowed is true, the window was moved forward to the limit.
• 202: the delivery is stored. Keep the artifact_id.
• 400: the request is wrong, and sending it again gets the same answer. field names what to fix. The code credential_in_url means the credential was put in the URL: move it to the Authorization header, and rotate it, because the URL may already be in a log.
• 401: the token or static key is missing, unknown, revoked or expired. With client credentials, ask for a new token once and send again. Otherwise, and after a second 401, do not retry. Check the header, then the connection's state on the Developer page.
• 401 from the token endpoint with invalid_client: the client id or secret is wrong, or the connection is revoked or expired. Do not retry.
• 403 with the code permission_denied: the connection does not hold the permission the call needs. The WWW-Authenticate header names it. Do not retry. Make a connection that may do what the operation needs.
• 403 with the code docs_origin_needs_sandbox: the request came from the documentation site with a production connection. Use a sandbox connection or the demo connection there.
• 403 with the code webhook_only: the source takes signed webhooks only, so nothing can push to it.
• 404: the source is not the company's, or the connection has nothing on the company.
• 409 with the code source_paused: the company has paused the source. Nothing in the request is kept, and Norra will not fetch it later. Stop sending. Once the source is resumed, send what was refused again, with the same idempotency keys. A webhook sender gets the same answer.
• 409 with the code key_reused: the idempotency key already stored a delivery with a different body. Nothing in this request is kept, and the first delivery stands. Do not retry it: a retry sends the same body under the same key, and a key names one body.
• 413: the delivery is over 8388608 bytes (8 MiB). Split it into smaller deliveries, each with its own idempotency key.
• 429: too many requests on this connection. Wait the number of seconds in Retry-After, then send the same request again.
• A 5xx, a timeout or a dropped connection: send the same request again, with the same idempotency key.

Retrying safely

A push carries an idempotency key, so sending it again stores nothing twice and returns the same receipt. Every push is safe to retry as long as the retry reuses the key and sends the same body. The same key with a different body is refused with 409 and key_reused.

• Retry a 429, a 5xx and a timeout. Do not retry another 4xx unchanged.
• Wait longer before each attempt, for example 1, 2, 4 and 8 seconds with some randomness added, up to a limit you choose.
• After a 429, wait at least Retry-After seconds.

Rate limits

A connection may make 60 requests a minute, reads and pushes together, bursting to 20. The 200, 202 and 429 answers carry three headers:

• RateLimit-Limit: requests allowed in the window.
• RateLimit-Remaining: requests left in the window.
• RateLimit-Reset: seconds until the window refills.

A client that reads RateLimit-Remaining can slow down before it gets a 429.