Error codes

ReferenceSep 27, 20264 min read

Errors use standard HTTP status codes, and the body always has the same shape. Every error links back to its entry on this page.

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_data",
    "message": "Missing required data: purchase_price.",
    "param": "data.purchase_price",
    "doc_url": "https://notriv.com/docs/api/errors#error-missing_data",
    "request_id": "req_9sLx..."
  }
}

Handle errors by code, which never changes. message is for people and may be improved over time. Include request_id when you contact support.

Keys and access

Code	Status	What to do
`api_key_missing`	401	No key was sent. Add the header Authorization: Bearer nrv_test_...
`api_key_invalid`	401	The key is wrong or incomplete. Copy it again, or create a new one.
`api_key_revoked`	401	The key was revoked. Create a new one in Developers.
`api_key_expired`	401	The key passed its expiry date, or its 24-hour roll overlap ended. Use the new key.
`api_key_in_query`	400	The key was put in the URL. Send it in the header instead, and roll the key.
`ip_not_allowed`	403	This key only works from certain IP addresses. Add this server’s IP to the key.
`account_inactive`	403	The account is suspended or pending. Contact support.
`https_required`	403	Use https://, not http://.
`test_mode_only`	403	Test helpers need a test key.

Limits and balance

Code	Status	What to do
`rate_limited`	429	Too many requests this minute. Wait for the Retry-After seconds, then retry.
`too_many_auth_failures`	429	Too many wrong keys from your address. Wait a minute and check your key.
`daily_limit_reached`	429	Your account hit its daily live-envelope limit. Contact support to raise it.
`usage_limit_reached`	402	No signatures left this period. Buy more at the buy_url in the error, then retry. Nothing was sent.
`request_too_large`	413	The request is over 30 MB.

Request problems

Code	Status	What to do
`parameter_missing`	400	A required parameter is missing. param names it.
`parameter_invalid`	400	A parameter has the wrong type or value. param names it.
`parameter_unknown`	400	A parameter name isn’t recognized. Usually a typo.
`invalid_json`	400	The body isn’t valid JSON.
`missing_data`	400	Required data values are missing. missing_keys lists all of them.
`unknown_data_key`	400	data has a name the document doesn’t use. The message lists the names it expects.
`signer_missing`	400	A role in the document has no signer. required_roles lists the roles.
`signer_without_fields`	400	A signer has nothing to sign in this document.
`no_signature_fields`	400	The PDF has no signature fields. Add tags, send fields, or set signature_page: true.
`no_fields_found`	400	A template upload had no tags or form fields.
`tag_invalid`	400	A tag in the PDF has an invalid role or name.
`file_invalid`	400	Not a PDF, damaged, or password-protected.
`file_too_large`	400	Over 25 MB or 200 pages.
`resource_missing`	404	Nothing with that ID in this mode. Check you’re using a test key for test objects.
`route_not_found`	404	That path doesn’t exist. Check the reference.

Envelope state

Code	Status	What to do
`envelope_not_draft`	409	Only drafts can be sent. This one was already sent or voided.
`envelope_not_sent`	409	This action needs a sent envelope that isn’t complete.
`envelope_completed`	409	Completed envelopes are legal records and can’t be voided.
`envelope_voided`	409	Already voided.
`signer_completed`	409	That signer already signed.
`signer_not_ready`	409	Signing order is on and an earlier signer hasn’t finished.
`file_not_ready`	409	The signed PDF and audit trail exist once everyone has signed.
`delivery_embedded`	409	Reminders only apply to email delivery.

Retries and server errors

Code	Status	What to do
`idempotency_key_reused`	422	This Idempotency-Key was used for a different request. Use a new key.
`idempotency_request_in_progress`	409	The first request with this key is still running. Retry in a moment.
`rate_limiter_unavailable`	503	A safety check couldn’t run, so the request was refused. Retry shortly.
`api_not_configured`	503	The API isn’t set up on this server. Contact support.
`internal_error`	500	Something failed on our side. Retry with the same Idempotency-Key.

Was this page helpful?