v2
User Interfaces
Configuration
Error Handling
Error handling for Universal API.
By default, endpoints will return a 200 OK message even if there are errors. If an error occurs, you will get a blank response from the endpoint. This document demonstrates different ways to handle errors within APIs.
Automatically Returning Errors
To automatically return errors from APIs, you can change the default behavior by setting the
-ErrorAction parameter of New-PSUEndpoint to Stop. Any errors will cause an 500 Internal Server Error to be returned with a list of the errors and stack trace.Terminating errors will always return a 500 Internal Server Error.
1
New-PSUEndpoint -Url "/error" -Endpoint {
2
throw "Uh oh!"
3
} -ErrorAction stop
4
​
5
New-PSUEndpoint -Url /error2 -Endpoint {
6
Write-Error "Whoa!"
7
} -ErrorAction Stop
Copied!
You will notice different behavior in Windows PowerShell and PowerShell 7 when calling REST APIs that return errors. In Windows PowerShell, you will receive a generic error that doesn't return the error message.
1
PS C:\Users\adamr> invoke-restmethod http://localhost:5000/error2
2
invoke-restmethod : The remote server returned an error: (500) Internal Server Error.
3
At line:1 char:1
4
+ invoke-restmethod http://localhost:5000/error2
5
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6
+ CategoryInfo : InvalidOperation: (System.Net.HttpWebRequest:HttpWebRequest) [Invoke-RestMethod], Web
7
Exception
8
+ FullyQualifiedErrorId : WebCmdletWebResponseException,Microsoft.PowerShell.Commands.InvokeRestMethodCommand
Copied!
In PowerShell 7, when an error is returned, you will see the error message returned.
1
PS C:\Users\adamr\Desktop> invoke-restmethod http://localhost:5000/error
2
​
3
Invoke-RestMethod: Uh oh!
4
at , : line 2
5
at , : line 1
6
​
7
PS C:\Users\adamr\Desktop> invoke-restmethod http://localhost:5000/error2
8
​
9
Invoke-RestMethod: Whoa
10
at , : line 2
11
at , : line 1
Copied!
You can retrieve the error message in Windows PowerShell, by using the following syntax.
1
PS C:\Users\adamr> try { invoke-restmethod http://localhost:5000/error2 } catch { [System.IO.StreamReader]::new($_.Exception.Response.GetResponseStream()).ReadToEnd()}
2
Whoa!
3
at <ScriptBlock>, <No file>: line 2
4
at <ScriptBlock>, <No file>: line 1
Copied!
Manually Returning Errors
To manually return errors, you need to use the
New-PSUApiResponse cmdlet. This cmdlet allows you to define the status code and body for the response.In this example, we are returning a 404 error code from the endpoint.
1
New-PSUEndpoint -Url /broken -Endpoint {
2
New-PSUApiResponse -StatusCode 404 -Body 'Failed!'
3
}
Copied!
Similar to the automatic error codes, error codes returned manually will as display better in PowerShell 7. Here's an example of calling the endpoint.
1
PS C:\Users\adamr\Desktop> invoke-restmethod http://localhost:5000/broken
2
​
3
Invoke-RestMethod: Failed!
Copied!
If called from Windows PowerShell, you will receive an error similar to the one returned automatically.
1
PS C:\Users\adamr> invoke-restmethod http://localhost:5000/broken
2
invoke-restmethod : The remote server returned an error: (404) Not Found.
3
At line:1 char:1
4
+ invoke-restmethod http://localhost:5000/broken
5
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6
+ CategoryInfo : InvalidOperation: (System.Net.HttpWebRequest:HttpWebRequest) [Invoke-RestMethod], Web
7
Exception
8
+ FullyQualifiedErrorId : WebCmdletWebResponseException,Microsoft.PowerShell.Commands.InvokeRestMethodCommand
Copied!
You can choose to return error codes if certain conditions are met by using your PowerShell script within the endpoint.
1
New-PSUEndpoint -Url /user/:name -Endpoint {
2
if ($Name -eq 'User')
3
{
4
@{ UserName = "Adam" }
5
}
6
else
7
{
8
New-PSUApiResponse -StatusCode 404 -Body 'Unknown user!'
9
}
10
​
11
}
Copied!
API
Last modified 5mo ago
Copy link