REST API

Errors

Every error is an RFC 9457 problem document with the media type application/problem+json:

{
  "type": "https://www.esoppari.fi/en/docs/api/errors#validation_failed",
  "title": "The request has invalid fields",
  "status": 422,
  "code": "validation_failed",
  "request_id": "7f2c0d3e-1b4a-4f7e-9c11-0a8e2b5d6c33",
  "errors": [
    {"pointer": "/signers", "code": "signer_email_invalid"}
  ]
}
  • Branch on code, never on title or detail. A code never changes its meaning. type links to this guide; the tables below name each code.
  • errors lists every invalid field of a 422, with a JSON Pointer to it.
  • Quote request_id when you contact support.

Codes

Status code What to do
400 invalid_request The body is not valid JSON, or a parameter has the wrong type. Fix the call.
400 idempotency_key_invalid The Idempotency-Key header is empty or longer than 255 characters.
401 missing_api_key, invalid_api_key See Authentication.
403 tenant_suspended Your organisation is not active. Contact your administrator.
403 no_active_subscription Your organisation has no active plan. Choose one in the admin portal.
403 forbidden API keys cannot use this operation.
404 signing_request_not_found, signer_not_found The id names nothing your organisation has.
404 webhook_endpoint_not_found, webhook_delivery_not_found, webhook_event_not_found The id names nothing your organisation has, or the event is older than 30 days.
404 creation_session_not_found, embed_origin_not_found The id or the origin names nothing your organisation has.
404 signed_document_not_ready The request has no signed PDF yet.
404 source_document_not_available Only a draft serves its uploaded PDF. Download the signed PDF instead.
404 not_found No endpoint has this path. Check the path against the API reference.
405 method_not_allowed The endpoint does not take this HTTP method.
409 request_not_draft The request was sent already. Only a draft can be changed.
409 creation_session_open A send of a draft that an open creation session owns. Its page sends it. Do not change or delete such a draft: the next send of the page revises it.
409 request_not_pending The request is not waiting for signatures.
409 request_busy, document_not_prepared The service is working on the request. Retry after a few seconds.
409 archive_renewal_not_enabled The draft is enrolled in archive renewal, which your organisation no longer has. An administrator must change the draft in the portal.
409 signer_not_invited The signer signed, declined or was not invited yet.
409 signer_not_withdrawable The signer signed, declined, expired or was withdrawn already. Only a pending or invited signer can be withdrawn.
409 withdraw_leaves_no_signature Nobody signed yet, so the last signer cannot be withdrawn. Cancel the request instead.
409 webhook_delivery_pending The delivery is still pending, or it is a test and another test of the endpoint is pending. Wait for its result before you send it again.
409 embed_origin_exists Your organisation has this embed origin.
409 webhook_endpoint_disabled The endpoint is disabled. Enable it, then send the deliveries again.
412 precondition_failed The draft changed since your read. Get it again, then retry with the new ETag.
413 body_too_large, file_too_large The PDF is larger than 10 MiB, the logo is larger than 1 MiB, or a JSON body is larger than 256 KiB.
422 validation_failed See errors for each field.
422 draft_incomplete The draft cannot be sent yet. Get it and complete it.
422 webhook_endpoint_limit Your organisation has 10 webhook endpoints. Delete one first.
422 embed_origin_limit_reached Your organisation has 10 embed origins. Remove one first.
422 creation_session_limit_reached Your organisation has 100 open creation sessions. A session no longer counts after it is sent, cancelled or expired.
428 precondition_required A PUT has no If-Match header. Get the draft, then send its ETag.
429 rate_limited Wait the seconds of the Retry-After header. See Rate limits.
429 resend_too_soon The signer got an invitation email less than 3 minutes ago. Wait the seconds of the Retry-After header.
500 internal_error A fault on our side. Retry later and quote request_id.
503 service_unavailable Retry after the seconds of Retry-After. The call may have run, so retry a create with the same Idempotency-Key.

Field codes

code Field
document_required, document_not_found /document_id: the upload is missing or expired.
file_required, pdf_invalid, pdf_encrypted, pdf_already_signed, pdf_active_content /file of an upload.
expiry_past, expiry_not_future, expiry_too_far /expires_on. The last day must be before the year 9999.
reminder_too_long /reminder_interval_days: no reminder would be sent before the expiry.
signers_required, signer_email_invalid, signer_name_invalid, signer_email_duplicate, signer_details_invalid, signer_eid_country_unavailable /signers
order_type_invalid /order_type
processing_basis_invalid, processing_purpose_too_long /processing_basis, /processing_purpose
retention_category_invalid /retention_category
completion_delivery_invalid /completion_delivery
group_unavailable, default_group_inactive /group_id: the group is not an active group of your organisation.
too_long, invalid_value, out_of_range, too_many_signers A field outside the limits of the API reference: a length, an enum, a range, a NUL character in a text field, or more than 50 signers. The pointer names the field, for example /signers/2/name.
unknown_field A field that the body of the operation does not take, for example a typo. The pointer names it, for example /signers/0/emial. A key that is not lowercase letters, digits and _ gets the pointer of its object.
limit_out_of_range, cursor_invalid, status_invalid /limit, /cursor, /status of a list.
required, colour_invalid Any colour field of /v1/branding/colours: send all five, null for the platform colour. See Branding.
primary_low_contrast, primary_like_decline /primary_colour
decline_not_red, decline_low_contrast /decline_colour
secondary_low_contrast /secondary_colour
link_low_contrast /link_colour
logo_unsupported, logo_dimensions, logo_too_detailed /file of a logo.
url_invalid, url_not_https, url_port_not_allowed, url_ip_literal, url_userinfo, url_blocked_address /url of a webhook endpoint. See Webhooks.
description_invalid, event_type_unknown /description, /event_types of a webhook endpoint.
recover_since_too_old /since of a recover: the log keeps 30 days.
url_invalid /success_url, /cancel_url of a creation session: an absolute https URL.
embed_origin_required, embed_origin_not_allowed, embed_origin_unknown /embed_origin: an embedded session names one of your embed origins, and a hosted one names none. See Creation sessions.