Reference

Errors

Errors use standard HTTP status codes and always have the same JSON shape. Branch on code in your software, and show message to people.

Error format

JSONResponse · 422

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_recipient",
    "message": "recipients[1]: Enter a valid email",
    "param": "recipients.1",
    "doc_url": "https://readyink.ai/developers/errors/"
  }
}

Property	Meaning
`type`	The broad category. See the table below.
`code`	The specific reason. Branch on this.
`message`	A sentence you can show a person. It may change, so don't match on it.
`param`	The input it's about, as a dot path like `recipients.1` or `fields.3.x`. Not always present.
`doc_url`	A link to help for this error.

Some errors add more details: insufficient_tokens adds needed, available and checkout_url; not_ready_to_send adds problems; quote_changed adds tokens.

Error types

`type`	Usual status	Meaning
`invalid_request`	400, 413, 415, 422	Something in the request needs fixing.
`authentication_error`	401	The API key is missing, wrong or revoked.
`payment_required`	402	Not enough tokens.
`forbidden`	403	The key can't do this.
`not_found`	404	No such object in this mode.
`conflict`	409	The document's current state doesn't allow this.
`rate_limit_error`	429	Too many requests.
`api_error`	5xx	Something went wrong on our side.

Error codes

Status	Code	Meaning	How to fix
400	`invalid_json`	The body isn't valid JSON.	Check the JSON and the `Content-Type` header.
400	`invalid_multipart`	The multipart body couldn't be read.	Send `file` and `data` as form fields.
400	`idempotency_key_required`	Send or cancel without an `Idempotency-Key`.	Add the header.
400	`idempotency_key_too_long`	The key is over 200 characters.	Use a shorter key, such as a UUID.
401	`missing_key`	No API key was sent.	Add `Authorization: Bearer …`.
401	`invalid_key`	The key is wrong or was revoked.	Check the key, or create a new one.
402	`insufficient_tokens`	Not enough tokens to send.	Buy tokens at `checkout_url`, then send again.
404	`not_found`	No such document, recipient or field in this mode.	Check the ID, and whether you're using a live or test key.
409	`duplicate_email`	That email is already on the document.	Use a different email, or update the existing recipient.
409	`not_editable`	The document was sent, so this can't change.	Cancel and create a new document.
409	`bad_state`	The document isn't in the right status, or the PDF was already uploaded.	Check `status` and `file_status`.
409	`file_not_ready`	The PDF is still processing.	Wait until `file_status` is `ready`.
409	`quote_changed`	The cost changed since your quote. The error includes `tokens`.	Get a new quote and send again.
409	`idempotency_conflict`	The same key was used for a different request.	Use a new key for a new action.
409	`not_completed`	The document isn't completed yet.	Wait until `status` is `completed`.
413	`file_too_large`	The PDF is over 25 MB.	Compress or split the PDF.
415	`unsupported_media_type`	Unsupported content type for the upload.	Use `multipart/form-data` or `application/pdf`.
422	`invalid`	A value isn't allowed. `message` says which.	Fix the input described in `message`.
422	`validation_failed`	The request didn't pass validation.	Read `message` and `param`.
422	`invalid_limit`	`limit` isn't between 1 and 100.	Use a number from 1 to 100.
422	`invalid_date`	A date isn't a valid ISO 8601 time.	Use a format like `2026-11-09T15:04:05Z`.
422	`invalid_recipient`	A recipient isn't valid.	Check `name`, `email` and `mobile`.
422	`empty_file`	The uploaded file is empty.	Upload the PDF again.
422	`not_a_pdf`	The file isn't a PDF.	Convert it to PDF first.
422	`missing_file`	No file was attached.	Attach the PDF as `file`.
422	`invalid_field`	A field isn't valid. In a batch, nothing was added.	Fix the one named in `param`, like `fields.3.x`.
422	`invalid_fields`	The request had no fields, or more than 200.	Send 1 to 200 fields per request.
422	`not_ready_to_send`	Something must be fixed before sending. The error includes `problems`.	Fix each problem, then send again.
429	`rate_limited`	Too many requests.	Wait `Retry-After` seconds.

Retries

Retry: 429 (after Retry-After seconds) and 5xx errors (with growing waits, such as 1, 2, 4 and 8 seconds).
Don't retry unchanged: 400, 401, 402, 404, 409, 413, 415 and 422. Fix the request first.
For send and cancel, always reuse the same Idempotency-Key when you retry, so nothing happens twice.

Contacting support about an error

Include the code, the message, the document ID and roughly when it happened. Never send your API key.

Something unclear or missing? Email info@readyink.ai or use the contact page. A real person will reply.