Errors
Read the error body (errorCode, message, details), branch on the first three parts of the code, use the 319-1, 319-2 or 319-3 category for default handling, and quote the full code to support.
The error body
When a request fails, the Invoice Tools API answers with an HTTP error status and a JSON body. Error handling (opens in a new tab) in Swagger describes it, with an example.
A request that needs a feature the system no longer supports fails with 319-3-3 and the HTTP status 400:
{
"errorCode": "319-3-3-1705338792",
"message": "Unsupported",
"details": "Country not supported"
}
In Swagger's examples, message is the short name of the error, and details says more about it or is null. Swagger's schema lists all three fields as required strings, so make sure that a client generated from it accepts null in details.
Read an error code
An error code has several parts, separated by hyphens. Each part answers a different question:
| Part | Example | Use it to |
|---|---|---|
| The first two parts | 319-2 | Find the category, which tells you what to do by default |
| The first three parts | 319-2-4 | Identify the specific error. Branch on this in your code |
| The whole code | 319-2-4-1704965684 | Point to this one occurrence. Quote it when you contact support |
The last part is unique to each occurrence. Compare only the first three parts with the codes in the table of error codes (opens in a new tab), and do not match on the text of message or details.
Categories
The second part of the code is the category. As a rule of thumb, 319-2 errors are caused by user input, and 319-3 errors are due to malformed API requests. Use the category for the default handling, and give a specific code its own handling where you need to. Codes that need their own handling lists the ones that deserve a closer look.
319-1: unexpected error
319-1-2 is the only code in this category. It comes with the HTTP status 500. Try again in a little while, and wait longer between attempts if it keeps failing. If the problem persists, contact Waya's technical support with the full error code, as described under Contact support.
Before you send a create request again
The first attempt may have been processed before the error came back. Look an invoice up by its externalNumber with Find invoices before you create it again, and do the same for a credit with Find credits (opens in a new tab). A direct payment can be sent again as it is: its externalNumber must be unique, and 319-2-6 tells you it is already registered.
319-2: user input
These errors are caused by the data in the request, for example an invalid debtor, email address or discount (319-2-7, 319-2-15 and 319-2-21). Show message to the person who can correct the data, such as the user who created the invoice in your system, and add details when it is not null. Then correct the data and send the request again.
A few 319-2 codes are about access, about a missing resource or about the state of an invoice, not about data. Codes that need their own handling covers them.
319-3: malformed request
These errors mean that the request is wrong, or that it uses something your integration or client is not set up for. Fix the integration instead of retrying, because the same request fails in the same way again. Do not show the error text to your users.
Log the full error code and the HTTP status, together with the externalNumber or id of what you were sending. For example, 319-3-1 is a schema validation error, and 319-3-22 and 319-3-23 mean that your own sums did not match Waya's, as described under Validate the sums.
Codes that need their own handling
These specific codes call for something other than the default of their category. Swagger (opens in a new tab) lists every error code.
| Code | What to do |
|---|---|
319-2-5 | The token was not accepted. Send the authorization token, not the authentication token, and renew it before it expires |
319-2-46 | You are authenticated, but the permissions set on your integration do not allow the request. Ask your Waya contact |
319-2-4 | Check the ID, and that you ask for the right type of entity: IDs are unique within one entity type only |
319-2-6 | The resource already exists, so do not create it again |
319-2-45 | The request needs the invoice to be in another state, for example when you delete an invoice that has already been sent to the debtor. Credit the invoice instead |
319-3-3 | The request needs a feature that is no longer supported, or no longer enabled for your integration or client. Stop using it, or ask your Waya contact |
319-3-46 | The invoice channel is not active yet, or it has been disabled. Ask your Waya contact |
Contact support
If you cannot resolve an error, or a 319-1 error persists, email Waya's technical support at techsupport@waya.se. Include:
- the full error code, for example
319-2-4-1704965684 - the
idof the invoice, if the request concerned one
To follow an invoice once it is sent, see After sending.