Error Handling

The Inspakt API always returns HTTP 200. Success or failure is determined by the success field in the response body, and the specific error by error.name.

---

Response structure

Success

{
  "version": "1.X.X",
  "success": true,
  "payload": { ... }
}

Failure

{
  "version": "1.X.X",
  "success": false,
  "error": {
    "name": "Envelope.NotFound",
    "description": "The requested envelope does not exist.",
    "context": {}
  }
}

Field	Type	Description
error.name	string	Stable machine-readable error identifier. Use this for conditional logic.
error.description	string	Human-readable explanation. Do not rely on this for logic — it may change.
error.context	object	Additional data specific to the error (e.g. current status). May be empty.

tip

Always check success first, then branch on error.name. Error names follow the Resource.ErrorType pattern and are guaranteed stable across API versions.

---

Error reference

Envelopes

Name	Description	Context fields
Envelope.NotFound	The envelope does not exist or does not belong to your team.	—
Envelope.NotDeletable	The envelope cannot be deleted in its current status. Only draft envelopes can be deleted.	—
Envelope.NotFinalized	The audit log was requested but the envelope is still draft or sent. Available for finalized, voided, and expired envelopes.	status
Envelope.Closed	A void was attempted on an envelope that is already closed (voided, finalized, or expired).	—
Envelope.AuditNotFound	The audit log PDF could not be generated.	—

Templates

Name	Description
Template.NotFound	The template does not exist or does not belong to your team.

Recipients

Name	Description
Recipient.NotFound	The recipient does not exist on the specified envelope or template.
Recipient.HostRecipientBound	The recipient cannot be removed because a host relationship depends on it.
Recipient.DelegatorRecipientBound	The recipient cannot be removed because a delegator relationship depends on it.

Documents

Name	Description
Document.NotFound	The document does not exist on the specified envelope or template.

Fields

Name	Description	Context fields
Field.NotFound	The field does not exist on the specified envelope or template.	—
Field.AssignmentInvalid	The recipientId does not belong to the envelope or template.	—
Field.ConfigurationInvalid	The config object contains invalid values for the given field type.	—
Field.IdentifierNotUnique	A field with the same identifier already exists.	—

General

Name	Description
BadRequestError	The request body is malformed or contains invalid values.

---

Handling errors in code

const response = await fetch(
  'https://next.inspakt.com/api/v1/key/envelopes/env_01hx.../send',
  { headers: { 'X-Inspakt-Api-Key': apiKey } }
);

// HTTP status is always 200 — check the body
const body = await response.json();

if (!body.success) {
  switch (body.error.name) {
    case 'Envelope.NotFound':
      // The envelopeId is invalid or was deleted
      break;
    case 'Envelope.Closed':
      // Already finalized or voided — no action needed
      break;
    default:
      // Unexpected error — log and alert
      console.error('Unhandled API error:', body.error);
  }
}

---

Network-level errors

The success: false pattern only applies to application-level errors returned by Inspakt. Standard HTTP errors (4xx, 5xx) may still occur for infrastructure reasons such as authentication failures, rate limiting, or transient outages.

HTTP Code	Cause	Action
401	Missing or invalid X-Inspakt-Api-Key header.	Check your API key.
403	Key exists but lacks permission for this resource.	Contact your account manager.
429	Rate limit exceeded.	Back off and retry.
5xx	Transient server error.	Retry with exponential backoff.

Retry strategy for 5xx

Attempt	Wait before retry
1	1 s
2	2 s
3	4 s
4	8 s

Do not retry on 4xx — these indicate a problem with the request itself.