API trigger fail? Here’s why you got 422 error

Just yesterday, I got an email from a participant in one of my recent SAP Build CodeJams in the Netherlands, who was having trouble calling the SAP Build Process Automation API to trigger his process. I get these questions all the time.

Well, I have documented (almost) all of the reasons why your API call could fail (except for the fact that you have no internet connection), and I mapped them to the status code you would receive.

I am really proud of this documentation – I try to anticipate what problems you might face and, through a lot of trial and error, I try to determine what each status code means. But the documentation is buried in my tutorial for the CodeJam, so I’d thought I give it it’s own blog post.

So here’s what could go wrong with your API call:

• 403: The destination to the SAP Build Process Automation API is not configured properly. Make sure the client ID, secret, service URL and authentication URL (with /oath/token path) are set correctly. Do not add user/password for the authentication URL.
• 404: The API did not recognize the name of your process (i.e., definitionId in the request body mapper) or the path to the service is wrong – both in the create tab. A wrong path, of course, could be caused by a problem in either the base URL or the path of the create action.
• 415: You did not send the Content-Type request header.
• 422: This basically means that the API heard your call but it didn’t like something in the request body. This is probably the most common and vexing problem. More on this error below.
• 500: This may mean that your URLs are wrong, especially, you may have the wrong URL for OAuth authentication, such as you forget to add the path /oauth/token.

Debugging 422 Error

Getting 422 when calling your trigger is the most common problem. There are essentially 2 reasons for this:

• The names of the trigger/input parameters that you sent do not match the parameters you defined (case sensitive).
• The values you sent are not of the right data types. For example, you sent text for a number field or an invalid date format (dates must be in this format: 2023-01-31).

It only takes a few minutes to debug such an error. It helps to do the following:

• Check the trigger in your deployed process to see what the process is expecting.
• Use the browser’s Developer Tools (and then select the Network tab) to check what values were sent. For example, from SAP Build Apps, run a test of the trigger from the Data tab, and you will get a call labeled with the name of the destination. Then look at the payload for what request body was sent.

Now match them up and see what values are mislabeled or missing.

Startling discovery

But while experimenting for this blog, I found out something interesting: the API call does NOT care what parameters you send.

That’s right.

You can send whatever parameters you want, or you can even not send the context part of the payload at all. You can send parameters with the wrong name, or extra parameters.

The 422 error occurs only when you use the parameters in your workflow, for example, displaying them in a form, and they are of the wrong data type. More specifically, it can occur when you define a date field in a form and you map it to a trigger parameter that is not formatted as a date or to a parameter that has not been sent at all.

I am not sure how you catch such bad input inside your process – comment below if you know.

Documentation on SAP Business Accelerator Hub

I never took notice of it, but there is helpful documentation about the error messages in the API documentation. For example, it explains that 404 is thrown when the definitionId is missing or the specified process instance does not exist, so it can be quite helpful.

But not all the messages are fully explained, and that is what I tried to do above.