Errors

Errors use the HTTP status and this body. Branch on code, which is stable. message can change.

{
  "error": {
    "code": "recipient_invalid_email",
    "message": "The document could not be sent: recipient invalid email.",
    "param": "recipients.0.email",
    "request_id": "req_4f9a1c7e2b8d4a60"
  }
}

Check the status first, then branch on code for the cases your app can act on, and log request_id for the rest so support can find the request.

const response = await fetch("https://www.inkly.so/api/v1/documents", { method: "POST", headers, body: JSON.stringify(body) })

if (!response.ok) {
  // A per-IP 429 from the network is plain text, so the body is not always JSON.
  const { error } = await response.json().catch(() => ({ error: { code: "not_json" } }))

  switch (error.code) {
    case "template_not_found":
      // Fix the template ID in your settings, then send with a new Idempotency-Key.
      break
    case "monthly_allowance_exceeded":
      // Hold the send until the 1st, or move the workspace to a bigger plan.
      break
    default:
      // param points at the bad input, such as "recipients.0.email".
      throw new Error(`${error.code} at ${error.param ?? "request"} (request ${error.request_id})`)
  }
}

Any endpoint can return these:

• invalid_api_key401Provide a valid API key in the Authorization header.What to do: Send Authorization: Bearer followed by the whole key. If the key was revoked, create a new one on API settings.
• api_key_in_query400Send API keys in the Authorization header, never in a URL.What to do: Move the key from the URL to the Authorization header, and create a new key, because the old one may now be in logs.
• api_disabled403 or 503API access is disabled for this workspace (403) or for everyone for now (503).What to do: 403: the workspace's API access was turned off, so contact support. 503: API access is paused for everyone; retry later.
• plan_required403API access requires Pro or Teams.What to do: The workspace needs Pro or Teams for the API, and for features such as sequential signing.
• scope_required403This key does not have the required scope.What to do: Use a Read and send key. A Read key cannot send, remind, or void.
• rate_limited429Too many requests. Try again after the indicated reset time.What to do: Wait as long as Retry-After says, then retry the same request with the same Idempotency-Key.
• idempotency_not_supported400This endpoint does not support Idempotency-Key.What to do: Leave out the Idempotency-Key header. Only the two send endpoints accept it.
• internal_error500The request could not be completed. Try again.What to do: Retry with the same Idempotency-Key. If it keeps happening, contact support with the request_id.

• api_key_in_query400Send API keys in the Authorization header, never in a URL.What to do: Move the key from the URL to the Authorization header, and create a new key, because the old one may now be in logs.
• dropdown_options_invalid400A dropdown's options are missing, duplicated, or not valid.What to do: Give the dropdown 2 to 50 different, non-empty options.
• field_out_of_bounds400A field falls outside the page.What to do: param names the field. Keep x + width and y + height at most 1, and page within the PDF's page count. Round values down at the page edge.
• idempotency_key_required400Provide an Idempotency-Key header.What to do: Add an Idempotency-Key header, built from the record you are sending for, such as crm-8841-send-1.
• idempotency_not_supported400This endpoint does not support Idempotency-Key.What to do: Leave out the Idempotency-Key header. Only the two send endpoints accept it.
• invalid_request400The request is invalid.What to do: param names the input that failed, such as recipients.0.email. Fix the request and send it with a new Idempotency-Key.
• invite_message_too_long400The invitation message is too long.What to do: Keep message to 2,000 characters.
• prefilled_field_invalid_label400A prefilled field's label is not valid.What to do: Use a non-empty label on one line. Labels such as party_1_name are reserved.
• prefilled_field_invalid_value400A prefilled value contains text that cannot be used.What to do: Use one line of up to 500 characters, in Latin or Cyrillic text with standard punctuation, without emoji.
• prefilled_value_conflict400Prefilled fields with the same label must have the same value.What to do: Give every prefilled field with the same label the same prefill_value.
• recipient_invalid_email400A recipient's email address is not valid.What to do: param names the recipient. Correct the address.
• recipient_missing_email400A recipient has no email address.What to do: Add an email for every recipient, including those with delivery: link.
• unknown_field400This field is not supported.What to do: Remove the field named in param, or correct its spelling. Field names are lowercase with underscores.
• unknown_prefilled_field400This prefilled field is not in the template.What to do: param has the label. Match it to a label in the template's prefilled_fields from GET /templates/{id}.

• invalid_api_key401Provide a valid API key in the Authorization header.What to do: Send Authorization: Bearer followed by the whole key. If the key was revoked, create a new one on API settings.
• api_disabled403 or 503API access is disabled.What to do: 403: the workspace's API access was turned off, so contact support. 503: API access is paused for everyone; retry later.
• plan_required403API access requires Pro or Teams.What to do: The workspace needs Pro or Teams for the API, and for features such as sequential signing.
• scope_required403This key does not have the required scope.What to do: Use a Read and send key. A Read key cannot send, remind, or void.
• sending_paused403Sending is paused for this workspace. Contact support.What to do: Sending is paused for this workspace. Contact support.
• storage_limit_reached403This workspace has reached its document storage limit. Upgrade your plan or email hello@inkly.so for more storage, then retry with a new Idempotency-Key.What to do: Upgrade the plan or email hello@inkly.so for more storage, then send with a new Idempotency-Key.
• void_not_allowed403Only the document's creator or a workspace admin can void it.What to do: Use a key created by the document's sender or a workspace admin.

• attachment_not_found404Attachment not found.What to do: Get attachment IDs from the recipient's attachments in GET /documents/{id}.
• document_not_found404Document not found.What to do: Check the ID, and that the document is in this key's workspace.
• template_not_found404Template not found.What to do: Check the ID with GET /templates, and that the template is in this key's workspace.
• upload_not_found404Upload not found.What to do: Check upload_id is from POST /uploads made with a key in this workspace.
• upload_expired410This upload has expired. Create a new upload and try again.What to do: Uploads last one hour. Start a new upload, PUT the file again, and send with a new Idempotency-Key.

• certificate_not_ready409The certificate is not ready. Retry shortly.What to do: The certificate is still being made. Retry in a few seconds.
• document_changed409The document or template changed while it was being sent. Retry with a new Idempotency-Key.What to do: Nothing was sent. If you edited the template, check its roles with GET /templates/{id}, then send again with a new Idempotency-Key.
• document_not_completed409This document is not completed.What to do: Wait for the document.completed webhook, then download.
• document_not_voidable409Only sent documents can be voided.What to do: Only documents that are out for signature can be voided. Completed, declined, and voided documents cannot.
• idempotency_key_reused409This idempotency key was used with a different request.What to do: This key already sent a different body. If you changed the request on purpose, use a new key; if not, send the original body.
• idempotency_request_in_progress409A request with this idempotency key is still running.What to do: The first request with this key is still running. Wait a few seconds and retry with the same key to get its result.
• reminder_cooldown409A reminder is already in progress or cooling down.What to do: A reminder went out recently. Try again later.
• reminder_not_available409Reminders are not available for this document.What to do: Only documents still out for signature, with someone left to sign by email, can be reminded.
• signed_pdf_not_ready409The signed PDF is not ready. Retry shortly.What to do: The signed PDF is still being saved. Retry in a few seconds.
• signing_link_unavailable409This signing link is not available.What to do: The document is no longer out for signature, or, with sequential signing, it is not this signer's turn yet. Wait for recipient.signed from the signer before them.
• upload_already_used409This upload has already been used to send a document.What to do: Each upload sends one document. Start a new upload for another document.
• upload_in_progress409Another request is processing this upload. Retry shortly.What to do: Wait as long as Retry-After says, then retry the same request with the same Idempotency-Key.
• upload_incomplete409The PDF has not been uploaded yet. PUT the file to upload_url, then retry.What to do: PUT the file to upload_url and wait for a 200 before you send. Then retry.

• body_too_large413The JSON body must be at most 64 KB.What to do: Send less in one request. Long messages and many prefilled values add up; the PDF itself goes to upload_url, not in the body.
• cc_recipient_cannot_have_fields422A CC recipient cannot be assigned fields.What to do: Point the field at a signer's ref, or make that recipient a signer.
• cc_recipient_duplicate_email422The same CC email address appears more than once.What to do: List each CC email once.
• cc_recipient_limit_exceeded422A document can have at most 5 CC recipients.What to do: Send at most 5 CCs.
• document_has_no_fields422The document has no fields.What to do: Add fields, or set use_markers to true with markers in the PDF.
• document_has_no_recipients422The document has no recipients.What to do: Add at least one recipient.
• document_has_no_signers422The document has no signers.What to do: Add at least one recipient with the signer role. CCs only get a copy.
• google_drive_not_connected422The template saves to Google Drive, but Drive is not connected.What to do: Reconnect Google Drive in Inkly, or turn off saving to Drive on the template.
• in_person_not_supported422Templates with in-person signers cannot be sent through the API.What to do: Send this template from the Inkly app, or change the role so it signs remotely.
• invalid_pdf422The uploaded file is not a valid PDF.What to do: The upload has ended. Check the file opens as a PDF, then start a new upload with it.
• marker_invalid422A field marker is malformed, wraps onto another line, starts in the middle of other text, does not fit on its page, or takes the document over 500 fields.What to do: Check each marker's syntax, keep it on one line with space before it, and stay under 500 fields. Fix the PDF and upload it again.
• marker_not_found422use_markers is true, but the PDF has no field markers Inkly can read. A scanned PDF has no text, so send fields with coordinates instead.What to do: Check the PDF has selectable text and the markers use {{type;signer=ref}}. For a scan, send fields with coordinates on the same upload.
• marker_page_unsupported422A page with a field marker uses text or layout Inkly cannot place a field on exactly. Fix the PDF, or send fields with coordinates instead.What to do: Export the PDF from a tool other than Microsoft Word, such as Google Docs, or send fields with coordinates on the same upload.
• marker_pdf_too_complex422The PDF is too large or complex for marker detection. Send fields with coordinates instead.What to do: Send fields with coordinates on the same upload, or send a smaller PDF.
• marker_unknown_recipient422A field marker names a signer that is not a signer ref in this request.What to do: Add a signer whose ref matches the marker's signer=, or correct the marker. The same upload can be sent again with a new key.
• pdf_too_many_pages422The PDF has more than 500 pages.What to do: The upload has ended. Split the PDF to 500 pages or fewer and start a new upload.
• prefilled_value_missing422A required prefilled field has no value.What to do: Send a value in prefilled_values for every required prefilled field.
• recipient_limit_exceeded422A document can have at most 25 recipients.What to do: Send at most 25 recipients, including CCs.
• selection_group_incomplete422A checkbox or radio group on the template is incomplete.What to do: Finish the template's checkbox or radio group in the Inkly editor, then send again.
• signer_has_no_fields422A signer has no field to fill in.What to do: Give every signer at least one field they fill in. A prefilled field does not count.

• monthly_allowance_exceeded429The monthly API document allowance has been reached.What to do: Sends start working again on the 1st at 00:00 UTC. Moving to Teams raises the allowance straight away.
• rate_limited429Too many requests. Try again after the indicated reset time.What to do: Wait as long as Retry-After says, then retry the same request with the same Idempotency-Key.

• internal_error500The request could not be completed. Try again.What to do: Retry with the same Idempotency-Key. If it keeps happening, contact support with the request_id.
• temporarily_unavailable503The service is temporarily unavailable. Try again.What to do: Retry the same request with the same Idempotency-Key after a short wait.