Error handling

Kivra uses conventional HTTP response codes to indicate the success or failure of an API request.

Status code in response to an API request

In general:

• Codes in the 2xx range indicate success.
• Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, invalid data, etc.).
• Codes in the 5xx range indicate an error with Kivra’s servers or a timeout. In this case it is safe to retry the request.

Error Messages

When the KIVRA API returns error messages, it does so in an extended JSON format.

Example error response

{ "code"          : 40400
, "short_message" : "Resource not found"
, "long_message"  : "There's no resource at the given URI."
}

An error has always the following properties:

Property	Description
code	The Kivra error code
short_message	A short description of the error
long_message	A longer and more verbose error message
details	A JSON format message with information on the validation error (not mandatory)

Extra properties, for further context, can also exist in the error object, for which long_message should include human-readable information on how to proceed. These are documented on a per-path/verb basis.

Extended details property for validation errors (status code 400)

The error messages in case of validation error can have an additional property called details that contains valid JSON format of the validation error, as in the following example:

{
  "code": 40001,
  "short_message": "Invalid Request",
  "long_message": "The request was invalid. The client should not repeat this request without modification",
  "details": [
    {
      "payment_multiple_options": {
        "options": [
          {
            "amount": ["Amount must be positive if payable is true"],
            "reference": ["should be at most 25 character(s)"],
            "type": ["is invalid"]
          }
        ]
      }
    }
  ]
}

Note

For Send content, many of the specific validation error codes (for example 40009, 40012, 40017, 40019, 40024, 40028 and 40044) are collected under 40001, with the specific validation problems described in the details property. This applies in sandbox from 2027-02-01 and in production from 2027-04-30.

Extended error code

The 5-digit extended error code is provided both in the body of the response and in the x-error-code field of the response header.

Error codes

In addition to descriptive error text, error messages contain machine-parseable codes. While the text for an error message may change, the codes will stay the same. The following table describes the codes which may appear when working with the API:

Code	Short Message	Long Message
40000	Request validation failed	The request payload does not pass required validation
40001	Invalid Request	The request was invalid
40002	Redirect URI Mismatch	The redirect_uri does not match the registered redirect_uri
40003	Invalid Scope	An invalid or insufficient scope was used
40004	Already registered	This user is already registered
40005	Error in phonenumber	The request can’t be processed due to phonenumber not meeting the required format
40006	Error in password	The request can’t be processed due to password not meeting the required format
40007	Error in email	The request can’t be processed due to email not meeting the required format
40008	Unprocessable Entity	The JSON payload was malformed. The client should not resend the same payload without first correcting the erroneous JSON payload.
40009	Error in SSN	The request can’t be processed due to SSN not meeting the required format.
40010	No action supplied or invalid	The action parameter was not supplied or invalid.
40011	Failed Extended Validation	The request can’t be processed due to SSN and/or mobile failed extended validation.
40012	Error in type	The request can’t be processed due to type field failing extended validation.
40013	Sendrequest already accepted	The request can’t be processed due to user have already an accepted sendrequest
40014	Invalid Status	The request can’t be processed due to invalid Status
40015	Invalid Token	Invalid access_token provided
40016	Invalid State	The request can’t be processed due to invalid State
40017	Invalid Campaigns	The request can’t be processed due to invalid campaigns
40018	Error in Company ID	The request can’t be processed due to Company ID not meeting the required format
40019	Invalid Files	The request can’t be processed due to invalid files
40020	Invalid Parties	The request can’t be processed due to invalid data for parties
40021	Invalid Bank Account	The request can’t be processed due to invalid bank account
40022	Missing Postal Address	The request can’t be processed due to missing postal address
40023	Invalid Contact Info	Invalid contact_info provided
40024	No Receiver Specified	None of ‘ssn’, ‘email’ or ‘vat_number’ has been specified as receiver
40025	Invalid OTP	The provided OTP is invalid or expired
40026	JSON payload was not an object	The JSON payload was malformed. Only JSON objects are supported
40027	Signature verification failed	Signup signature is invalid or signup data is altered
40028	UnsupportedFileType	The request can’t be processed due to a data file was provided using an unsupported type
40030	IconSizeError	The request can’t be processed due to the icon format not being compliant with the requirements
40031	PNG Missing Alpha Channel	Only PNG with alpha channel (PNG32) is allowed
40032	User doesn’t exist	No user exists with provided SSN
40033	Invalid query parameters	One or more query parameters were invalid, e.g. bad format, not supported
40035	Required header missing	One or more required headers were missing in the request
40036	Resource Already Exists	The resource you are trying to create already exists
40037	Agreement parties are not unique	All agreement parties must have a unique SSN
40038	The provided destination URL does not meet our requirements	It’s either not following the format https://subdomain.domain.tld/* or is not yet whitelisted in our system. Please contact us for support
40039	Cannot publish or update a canceled campaign	Cannot publish or update a canceled campaign
40040	Campaign must have an image	Cannot publish campaign without an image
40041	Invalid pay date	Pay date is in the past, too far in the future or not a bank day
40042	Invalid amount	The amount is out of range
40043	Invalid user preference	This preference is not supported
40044	Invalid OCR	The OCR did not pass validation
40045	Invalid option id	The option does not exist
40047	Invalid PDF	The supplied agreement PDF was invalid. Please check that the file is a valid PDF
40048	Invalid Label	The supplied labels do not match the required format
40049	Invalid Value For Expiration Days	Must be an integer within the allowed range, representing the number of days an agreement will remain in the system before it expires
40050	Form Response Error	Error processing form response
40098	Invalid barcode data	The barcode could not be created due to invalid barcode type
40100	Unauthorized	Supplied credentials were invalid
40101	Access Denied	The resource owner or authorization server denied the request
40102	Unauthorized Client	The client is not authorized to request an authorization code using this method.
40103	Invalid Grant	The provided authorization grant (e.g. authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.
40104	Invalid Client	Client authentication failed (e.g. unknown client, no client authentication included, or unsupported authentication method).
40105	Invalid Sendrequest	No sendrequest exists between sender and receiver, or sendrequest is not accepted.
40106	Email in use	This email address is already in use and can not be used.
40107	Phone number is already in use	This phone number is already in use and can not be used.
40108	Registration Code or Sendrequest Invalid	The Registration Code is invalid or no Sendrequest exists or has expired.
40109	Sendrequest or Share already exists or is blocked	An already existing Sendrequest exists or is blocked.
40110	Missing Print Integration	No print integration exists for the tenant
40111	Access Denied: Invalid OTP	The provided OTP is invalid or expired
40112	Access Denied: Insufficient Security Score	The requested resource requires a greater security score than the one associated with the current login method
40113	User does not exist with provided id	Contact us to enroll, make sure to include your id
40300	Forbidden	Access was denied to the given resource, authenticating will make no difference
40400	Not found	The resource was not found at the given URI at this time
40500	Method Not Allowed	The method specified is not allowed for the resource at the requested URI
40601	Invalid Accept Header	The Accept Header contains a non valid or unknown Content-Type
40915	Conflict	An attempt was made to create an object that already exists
41300	Request Entity Too Large, the sent payload exceeded the maximum size limit
42221	Request to retain content with unsupported content type
42900	Too Many Requests	Too many requests within this timespan have been made. Please try again later

Troubleshooting

In case you’re experiencing problems interacting with the API, make sure to collect the correlation id and provide our sender support (avsandare.support@kivra.com) with this information. The correlation Id can be found in the x-correlation-id header of all of Kivra’s API responses.