Error Handling

Practical guidance for handling failures: authentication, validation, resource and temporary problems.

1. Check the HTTP response

Inspect the HTTP status of every response before processing the body. Non-successful statuses indicate the request failed.

2. Check success

Where the response includes a success field, verify it before trusting the payload. A response with success: false should be treated as an error even if the HTTP layer looks fine.

3. Log the request_id

Log the request_id returned in the response envelope. It's the correlation identifier Undersign support uses to trace a request.

4. Log endpoint and transaction

Log the endpoint you called and your own internal transaction ID alongside the request_id so failures are traceable in both directions.

5. Handle failure categories

• Authentication failures: the credential is missing, malformed or inactive. Fix the credential; do not retry blindly.
• Validation failures: the request body is invalid. Inspect the response and correct the request before retrying.
• Resource failures: for example a template or request isn't found. Verify the identifier before retrying.
• Temporary failures: transient problems. Retry with an appropriate delay.

6. Avoid infinite retries

Cap retries and back off with increasing delays. See Rate Limits for operational guidance.

7. Error code reference

Every failure carries an error.code. Handle the code, not just the HTTP status:

Example check

const response = await fetch(url, options);
const data = await response.json();

if (!response.ok || data.success === false) {
  console.error({
    status: response.status,
    requestId: data.request_id
  });
  return;
}

Related