What does error 400 mean in the DocuSign API?

It means the request reached the server but contained at least one invalid parameter or malformed value. Unlike a 401 (authentication) or 404 (resource not found), a 400 is about the content of your request — the response body's message field names the problem.

Why do I get 400 only when sending, not when creating a draft?

Some validation runs only at send time — for example required tab values, recipient completeness, and formula evaluation. Creating with status: created defers those checks; sending with status: sent triggers them all at once.

Can DocuSign support tell me exactly what failed?

Yes. Provide the trace token from the X-DocuSign-TraceToken response header and the redacted request body; support can retrieve the server-side validation failure.

Is there a way to validate an envelope without sending it?

Create the envelope as a draft ( status: created ) in the demo environment first. Draft creation still validates structure, and the demo environment is free for unlimited testing.

Troubleshooting DocuSign API Error 400: Fixing Invalid Reque

A DocuSign API HTTP 400 "invalid request parameter" error means the server understood your call but rejected its contents — almost always a malformed JSON body, an invalid field value, or a parameter in the wrong place. The fastest fix is to read the errorCode and message fields in the response body, which name the exact parameter that failed, then validate your JSON against the envelope definition schema before resending.

Here is a systematic way to find and fix the problem.

Read the error response first

Every 400 response from the eSignature REST API includes a body like:

```json

{

"errorCode": "INVALID_REQUEST_PARAMETER",

"message": "The request contained at least one invalid parameter. Value for 'status' must be one of: sent, created, delivered."

}

```

Two habits save hours:

Log the full response body on every non-2xx call. The message usually names the offending field.
Log the API request ID (the X-DocuSign-TraceToken header). Support can look up the exact server-side failure from it.

The most common causes, in order of frequency

Cause	Typical symptom	Fix
Invalid enum value	`status`, recipient `type`, or event values rejected	Use exact allowed values; `status: sent` to send, `created` for drafts
Malformed JSON	Trailing commas, wrong nesting, arrays where objects expected	Validate the body with a JSON linter; compare against the envelope definition reference
Tab/field values out of range	Text tab over max length, bad date format, invalid anchor string	Check tab validation rules; dates in the documented format
Recipient definition incomplete	Signer missing `email` or `name`, routing order conflicts	Every recipient needs required fields; routing orders must be unique per level
Parameter in the wrong place	Query parameter that belongs in the body, or vice versa	Check the endpoint reference — create/send fields go in the JSON body
Wrong content type	Sending JSON without `Content-Type: application/json`	Set the header explicitly; some SDK defaults are form-encoded

A step-by-step debugging workflow

Reproduce the call in a REST client (Postman or curl) with the exact same body — this separates "my code is wrong" from "my request is wrong."
Strip the request to the minimum viable envelope: one document, one signer, one signature tab. If the minimal call succeeds, add fields back in batches until the 400 returns — the last batch contains the fault.
Diff against a working envelope. Create the same envelope in the DocuSign web UI, retrieve it via GET /envelopes/{id}, and compare its JSON structure to yours.
Check the base URI. A call sent to the wrong environment (demo vs production) usually returns 401, but mixed-up account IDs and envelope IDs across environments can surface as 400-class errors too.
If the message is opaque, open a support case with the trace token and the redacted request body.

Validation and tab-value errors deserve special attention

The single largest class of 400 errors involves tabs (fields). Common traps:

Value too long: text tabs have length limits; enforce your own max before sending.
Formula or calculated tabs: a broken formula reference invalidates the whole tab set.
Anchor string mismatches: anchor tagging is case- and whitespace-sensitive; an anchor that matches nothing is usually a warning, but an anchor with an invalid anchorUnits or offset value can fail the request.
Conditional fields: a required conditional tab whose parent value is missing can be rejected at send time.

If your integration also reads data back out of completed envelopes, validate outbound values against the same rules you use when you export tab and form data as JSON — mismatched formats cause round-trip failures. Teams newer to signature APIs can start with how to get started with an e-signature platform for the conceptual baseline.

Preventing 400 errors in production

Schema-validate every request body against a local copy of the envelope definition before sending; reject bad input in your own code where debugging is cheap.
Add retry logic only for 5xx and rate-limit responses. Retrying a 400 just repeats the same failure — fix the request instead.
Watch rate limits and payload ceilings separately; they return different error codes, and conflating them sends debugging in the wrong direction. Our review of DocuSign vs Dropbox Sign API rate limits and pricing tiers covers the operational side.
Keep SDKs current; older SDK versions occasionally serialize fields in ways newer API versions reject.

When API friction becomes a platform question: Nota Sign

If your team is spending more time fighting integration edge cases than shipping, it may be worth evaluating an alternative API. Nota Sign is FaDaDa's global e-signature platform — IDC-ranked #1 in China's e-signature software market for consecutive years — offering a developer-friendly e-signature REST API, legal coverage across 100+ countries and regions, and APAC compliance depth including regional data centers. With no per-seat fees and tailored plans for growing teams, it is straightforward to prototype against. Contact us for API credentials and a sandbox.