Common Quik! API Error Responses and First Checks

Common Quik! API Error Responses and First Checks

Overview

Quik! REST APIs return HTTP status codes and response details that can help identify the first troubleshooting step.

The exact validation rules and response structure can vary by endpoint, so always review the response body and the Swagger documentation for the API you are calling.

This page provides a practical starting point for common response categories.


Start with the Full Response

When an API request fails, capture both:

  • the HTTP status code
  • the complete response body

The status code identifies the general category of the issue. The response body may provide the specific reason the request was rejected.

Important: Do not share OAuth tokens, passwords, or sensitive client data when sending request or response examples to Quik! Support.


Common HTTP Status Codes

HTTP Status

General meaning

First checks

400 Bad Request

The request could not be processed because required data is missing, invalid, or not in the expected structure

Review the request body against the endpoint documentation. Check required properties, data types, nested objects, and JSON syntax.

401 Unauthorized

Authentication is missing, expired, or invalid

Generate a new OAuth token and confirm that the Bearer token is included in the request.

403 Forbidden

The authenticated account is not authorized for the requested resource or operation

Confirm the account, customer context, permissions, and any parent/child account relationship required by the endpoint.

500 Server Error

The request reached the service but an unexpected server-side error occurred

Retry only if appropriate. If the issue continues, capture the full sanitized request, response, endpoint, and timestamp for Quik! Support.

Note: Not every Quik! endpoint uses every status code in the same way. Endpoint-specific Swagger documentation is the source of truth for the operation you are calling.


400 Bad Request

A 400 response usually means the request reached the API but could not be processed as submitted.

First checks

  • Is the JSON valid?
  • Are all required properties present?
  • Are property names spelled correctly?
  • Are values using the expected data type?
  • Are nested objects in the correct location?
  • Are required arrays empty?
  • Does the request contain values that are valid for the selected endpoint and environment?

Example troubleshooting approach

If a large request returns 400:

  1. Save the original request.
  2. Compare it with the current Swagger request model.
  3. Correct obvious structure or type differences.
  4. If needed, remove optional sections one at a time.
  5. Resend after each change so you can identify which change affects the result.

For Direct to DocuSign specifically, the documented envelope request requires signSettings and at least one item in packagesData. Missing required values can result in a 400 response.

Related documentation:

Direct to DocuSign Model


401 Unauthorized

Quik! REST APIs use OAuth authentication.

A 401 Unauthorized response indicates that the OAuth token is missing, expired, or invalid.

First checks

  • Confirm that the request includes an Authorization header.
  • Confirm that the header uses Bearer authentication.
  • Generate a new OAuth token.
  • Retry the request with the new token.
  • Confirm that your application is not accidentally reusing an expired token.

Example header:

Authorization: Bearer <access_token>

REST authentication documentation:

REST Authentication


403 Forbidden

A 403 Forbidden response generally means the caller is authenticated, but the authenticated account is not authorized for the requested resource or account context.

First checks

  • Confirm which customer/account the OAuth token represents.
  • Confirm the customer or account identifier in the request.
  • If using a parent/child account model, confirm that the target account is authorized for the authenticated parent account.
  • Confirm that the product or API capability required by the request is enabled for the account.

For Direct to DocuSign, the customerID must match the authenticated customer or an authorized child account.


500 Server Error

A 500 response indicates that the service encountered an unexpected error while processing the request.

First checks

  • Confirm that the same request consistently produces the error.
  • Confirm the endpoint and environment.
  • Capture the exact timestamp and time zone.
  • Capture the complete response body.
  • Save a sanitized copy of the request that reproduces the issue.

If the same request repeatedly returns a server error, contact Quik! Support with the reproduction details.


A Successful HTTP Response Does Not Always Mean the Workflow Is Complete

For multi-step workflows, one request can succeed while a later request fails.

For example, Direct to DocuSign first generates PrintData and SignData, then uses those objects in a separate envelope request.

When troubleshooting, identify which call first produces an unexpected result.


What to Capture Before Contacting Support

Include:

  • HTTP method and endpoint
  • environment
  • HTTP status code
  • complete response body
  • sanitized request body
  • timestamp and time zone
  • steps required to reproduce the issue
  • request/response details for each call in a multi-call workflow

This information makes it easier to reproduce and isolate the behavior.


REST APIs (Preferred Method)

REST Authentication

Direct to DocuSign Model