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.
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.
New-PSUEndpoint -Url "/error" -Endpoint {throw "Uh oh!"} -ErrorAction stop​New-PSUEndpoint -Url /error2 -Endpoint {Write-Error "Whoa!"} -ErrorAction Stop
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.
PS C:\Users\adamr> invoke-restmethod http://localhost:5000/error2invoke-restmethod : The remote server returned an error: (500) Internal Server Error.At line:1 char:1+ invoke-restmethod http://localhost:5000/error2+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ CategoryInfo : InvalidOperation: (System.Net.HttpWebRequest:HttpWebRequest) [Invoke-RestMethod], WebException+ FullyQualifiedErrorId : WebCmdletWebResponseException,Microsoft.PowerShell.Commands.InvokeRestMethodCommand
In PowerShell 7, when an error is returned, you will see the error message returned.
PS C:\Users\adamr\Desktop> invoke-restmethod http://localhost:5000/error​Invoke-RestMethod: Uh oh!at , : line 2at , : line 1​PS C:\Users\adamr\Desktop> invoke-restmethod http://localhost:5000/error2​Invoke-RestMethod: Whoaat , : line 2at , : line 1
You can retrieve the error message in Windows PowerShell, by using the following syntax.
PS C:\Users\adamr> try { invoke-restmethod http://localhost:5000/error2 } catch { [System.IO.StreamReader]::new($_.Exception.Response.GetResponseStream()).ReadToEnd()}Whoa!at <ScriptBlock>, <No file>: line 2at <ScriptBlock>, <No file>: line 1
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.
New-PSUEndpoint -Url /broken -Endpoint {New-PSUApiResponse -StatusCode 404 -Body 'Failed!'}
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.
PS C:\Users\adamr\Desktop> invoke-restmethod http://localhost:5000/broken​Invoke-RestMethod: Failed!
If called from Windows PowerShell, you will receive an error similar to the one returned automatically.
PS C:\Users\adamr> invoke-restmethod http://localhost:5000/brokeninvoke-restmethod : The remote server returned an error: (404) Not Found.At line:1 char:1+ invoke-restmethod http://localhost:5000/broken+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ CategoryInfo : InvalidOperation: (System.Net.HttpWebRequest:HttpWebRequest) [Invoke-RestMethod], WebException+ FullyQualifiedErrorId : WebCmdletWebResponseException,Microsoft.PowerShell.Commands.InvokeRestMethodCommand
You can choose to return error codes if certain conditions are met by using your PowerShell script within the endpoint.
New-PSUEndpoint -Url /user/:name -Endpoint {if ($Name -eq 'User'){@{ UserName = "Adam" }}else{New-PSUApiResponse -StatusCode 404 -Body 'Unknown user!'}​}
​New-PSUEndpoint​
​Get-PSUEndpoint​
​Remove-PSUEndpoint​
​New-PSUApiResponse​
​Set-UASetting​