Verify and Troubleshoot

After submitting a delivery request, integrations must verify that the delivery has been processed successfully and handle any errors that may occur.

Delivery processing is asynchronous.

Do not assume immediate completion after submitting a delivery.

Delivery status should be checked when:

• The delivery request has been accepted and a deliveryId has been returned
• At least 15 minutes have elapsed since submission
• A previous status indicated Processing
• A retry attempt has been completed

The first status check should occur no earlier than 15 minutes after submission.

Processing time depends on:

• Number of envelopes
• Size of attachments
• Virus scanning duration
• Recipient resolution complexity
• Platform load

Delivery status is retrieved using GET /delivery/v1/deliveries/{deliveryId} (Get delivery report).

The delivery report is the authoritative source for delivery progress and outcomes.

The report includes:

• status — Processing or Completed
• totalEnvelopes
• deliveredEnvelopes

While status is Processing, envelopes are actively being processed.

When status becomes Completed, processing has finished and counts are final.

Important:

Completed does not mean all envelopes succeeded.
It means processing is finished.

Envelope outcomes are reported in the logs array.

Each log entry contains:

• envelopeId
• level
• key
• description
• Optional delivered

Important behavior:

• Successfully delivered envelopes are not listed in logs
• There may be multiple entries for the same envelopeId
• If delivered is omitted, the platform is still processing that envelope
• If delivered is false, the envelope failed

If delivery fails due to temporary conditions, the platform automatically retries processing.

Retries may continue for up to one hour.

During this period:

• status remains Processing
• logs entries may change
• deliveredEnvelopes may increase

After the retry window expires:

• status transitions to Completed
• Failed envelopes remain in logs

Do not resubmit while the delivery is still Processing.

To support integration logic, failures are categorized by logs[].key.

If you receive an unknown logs[].key, log it and treat it as a failure requiring investigation.

Correct the underlying issue before resubmitting affected envelopes.

These errors occur when the delivery POST request fails due to authentication or permission issues.

They are not reported in the delivery report logs.

Examples:

• Expired or invalid access token
• Invalid certificate
• Missing permissions for the sender

Authentication must be revalidated before retrying.

These errors occur when the delivery POST request fails due to temporary platform conditions.

They are not reported in the delivery report logs.

Examples:

• Service unavailable
• Timeout
• Internal processing error

These errors may be retried.

If the delivery POST request fails, the API returns a standard problem details response.

The platform uses:

• ProblemDetails for general errors (401, 403, etc.)
• ValidationProblemDetails for validation errors (400)

Example validation error:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "instance": "urn:trace:00-6985dee400000000d374b85cf06dc145-b92e494cc91c9129-01",
  "errors": {
    "$": [
      "JSON deserialization was missing required properties including s3BucketName"
    ]
  },
  "traceId": "00-6985dee400000000d374b85cf06dc145-b92e494cc91c9129-01"
}

Always log:

• HTTP status code
• status
• title
• type
• instance
• errors if present
• traceId if present
• Correlation identifiers

Retries must be implemented carefully.

Safe to retry:

• Platform errors
• Temporary network failures
• Temporary authentication failures

Do not retry automatically:

• Envelope validation errors
• Recipient errors
• Content errors

These require correction before resubmission.

Recommended retry pattern:

• First retry after 30 seconds
• Second retry after 2 minutes
• Third retry after 10 minutes
• Stop after defined maximum attempts

Avoid aggressive retry loops.

Integrations should log:

• deliveryId
• Submission timestamp
• Status check timestamp
• Delivery report: status, deliveredEnvelopes, totalEnvelopes
• For each logs entry: envelopeId, key, level, delivered if present
• Error responses for failed POST requests: HTTP status, type, title, instance, traceId

These logs support operational troubleshooting and reconciliation.

• Always verify delivery results
• Wait at least 15 minutes before first status check
• Do not resubmit while status is Processing
• Inspect envelope-level results
• Separate data errors from technical errors
• Log all failures
• Monitor trends

After verification and troubleshooting is implemented:

• Optimize delivery throughput
• Implement monitoring dashboards
• Integrate reporting and billing
• Automate operational alerts