Errors

How the Signkoi API reports errors: HTTP status codes, error types, stable error codes and request ids.

On this page

The error object
HTTP status codes
Error types
Error codes
Handling errors

Successful requests return 2xx. Anything else returns the same JSON error object, so you can always branch on error.type and error.code.

The error object

422 · application/json

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "The recipients.0.email field must be a valid email address.",
    "param": "recipients.0.email",
    "errors": {
      "recipients.0.email": ["The recipients.0.email field must be a valid email address."]
    },
    "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f"
  }
}

Error object fields
Field	Description
`type`	Broad family of the error (see below).
`code`	Stable, machine-readable reason. Branch on this; new codes may be added over time.
`message`	Human-readable explanation for logs and developers. It may change — never parse it.
`param`	The parameter the error is about, when there is one, e.g. recipients.0.email or files.1.
`errors`	Every invalid parameter with its messages (only on `validation_failed`).
`required_scope`	The scope the key is missing (only on `insufficient_scope`).
`request_id`	Same as the `X-Request-Id` response header. Include it when you contact support.

HTTP status codes

HTTP status codes
Status	Meaning
200, 201, 204	Success. 201 when something was created, 204 when there is no body (deletes).
400	The request is malformed.
401	No valid API key.
402	The plan’s monthly document allowance is used up.
403	The key lacks a scope, or the account is suspended.
404	The endpoint or resource doesn’t exist — or belongs to someone else.
405	The HTTP method isn’t supported on this endpoint.
409	The resource’s current state doesn’t allow the action (e.g. changing a sent envelope).
410	The resource is gone.
413	An upload is too large.
422	Validation failed, or a business rule did (e.g. a signer without a signature field).
429	Too many requests.
500, 502, 503	Something went wrong on our side. Retry with backoff.

Error types

Error types
Type	When
`invalid_request_error`	The request is invalid: bad parameters, unknown resource or endpoint, unreadable file.
`authentication_error`	The API key is missing, invalid, expired or revoked.
`permission_error`	The key is valid but may not do this.
`conflict_error`	The resource exists but its state doesn’t allow the action.
`billing_error`	A plan limit was reached.
`rate_limit_error`	Too many requests; slow down.
`api_error`	An error on our side.

Error codes

Authentication and access

Status	Codes
401	`api_key_missinginvalid_api_key`
403	`insufficient_scopeaccount_suspendedforbidden`

Requests

Status	Code	Meaning
422	`validation_failed`	A parameter is invalid; see `param` and `errors`.
404	`resource_missing`	No such envelope, recipient, template or webhook endpoint (or not yours).
404	`endpoint_missing`	Unknown URL. Check the path and the v1 prefix.
405	`method_not_allowed`	Wrong HTTP method for this endpoint.
422	`invalid_idempotency_key`	Idempotency-Key is empty or longer than 255 characters.
422	`idempotency_key_reused`	The Idempotency-Key was already used with a different request.
409	`idempotency_in_progress`	The first request with this key is still running. Retry shortly.

Files (creating envelopes)

Status	Code	Meaning
422	`file_required`	No file was sent.
422	`file_conflict`	Both `file` and `files[]` were sent; use one.
422	`too_many_files`	More than 10 files.
422	`invalid_file`	The upload is missing or broken.
422	`invalid_base64`	`content_base64` isn’t valid base64.
422	`file_not_pdf`	The file isn’t a PDF.
422	`invalid_pdf`	The PDF can’t be read (damaged or encrypted).
422	`invalid_json`	A multipart field that must hold JSON (recipients, fields, metadata, message) doesn’t parse.
413	`file_too_large`	A file, or all files together, exceeds the size limit.

For file errors param is file, files, files.N or files.N.content_base64, so you know which file failed.

Envelope state

Status	Code	Meaning
409	`envelope_not_draft`	Only drafts can be changed, deleted or sent. Void a sent envelope instead.
409	`envelope_not_sent`	The envelope isn’t out for signature (draft, finished or expired).
409	`nobody_to_remind`	No recipient is waiting for a reminder right now.
409	`recipient_finished`	The recipient has already finished.
409	`recipient_not_active`	It isn’t this recipient’s turn yet.
409	`recipient_in_person`	In-person signers get no emails; use a signing URL.
409	`not_recipients_turn`	A signing URL is only available to the recipient whose turn it is.
404	`file_not_ready`	The signed PDF and certificate exist once the envelope is completed.

Sending

Status	Code	Meaning
422	`no_recipients`	Add at least one recipient who signs, approves or views.
422	`missing_recipient_details`	A recipient lacks a name or email, or the data their verification method needs.
422	`unassigned_fields`	A field has no recipient, or belongs to someone who can’t fill fields.
422	`missing_signature_field`	Every signer needs at least one signature field.
422	`expired`	The expiry date has already passed.

Plans, limits and our side

Status	Code	Meaning
402	`plan_limit`	The monthly document allowance is used up.
422	`webhook_limit_reached`	An account can have up to 20 webhook endpoints.
429	`rate_limited`	Too many requests; wait for `Retry-After` seconds.
500	`internal_error`	Unexpected error. Retry; contact support with the request_id if it persists.

Handling errors

4xx errors mean the request needs to change — don’t retry them unchanged. The one exception is 429.
429 and 5xx are safe to retry with exponential backoff. Send POST requests with an Idempotency-Key so a retry never creates a second envelope.
Log the request_id of every failed request.

Branching on error.type

const res = await fetch(url, options);

if (!res.ok) {
    const { error } = await res.json();

    switch (error.type) {
        case 'rate_limit_error':
            // Wait for Retry-After seconds, then retry.
            break;
        case 'api_error':
            // Our side: retry with backoff, reusing the same Idempotency-Key.
            break;
        case 'billing_error':
            // plan_limit: ask the account owner to upgrade.
            break;
        default:
            // invalid_request_error, conflict_error, permission_error, authentication_error:
            // fix the request; don't retry it unchanged.
            console.error(error.code, error.param, error.message, error.request_id);
    }
}

404 instead of 403

To avoid revealing what exists, the API answers 404 resource_missing for resources that belong to someone else.