Errors and Troubleshooting
The Umbrella for Government API endpoints raise exceptions when something failed, such as missing or invalid parameters or formatted errors in the request path. We recommend writing code that gracefully handles all possible API exceptions.
Response Codes
The Umbrella for Government API endpoints use HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that resulted from a syntax, name, or format errors. Codes in the 5xx range indicate server errors.
| Status Code | Status Message | Description |
|---|---|---|
| 200 | OK | Success. Everything worked as expected. |
| 201 | Created | New resource created. |
| 202 | Accepted | Success. Action is queued. |
| 204 | No Content | Success. Response with no message body. |
| 400 | Bad Request | Likely missing a required parameter or malformed JSON. Review the syntax of your query. Check for any spaces preceding, trailing, or in the domain name of the domain you are trying to query. |
| 401 | Unauthorized | The authorization header is missing or the key and secret pair is invalid. Ensure that your API token is valid. |
| 403 | Forbidden | The client is unauthorized to access the content. |
| 404 | Not Found | The requested resource doesn't exist. Check the syntax of your query or ensure the IP and domain are valid. |
| 409 | Conflict | Exceeded the limit of a list, or attempted to delete an object that is in use. |
| 429 | Exceeded Limit | Too many requests made within a specific time period. You may have exceeded the rate limits for your organization or package. |
| 500 | Internal Server Error | Something wrong with the server. |
| 503 | Service Unavailable | Server is unable to complete request. A dependent service may be temporarily unavailable. |
If the response code is not specific enough to determine the cause of the issue, the server includes error messages in the response in JSON format.
Troubleshooting
Access tokens expire in one hour. You control the expiration date of your API keys.
API Key Creation
- You must have Full Admin privileges to create an API key.
- Your Umbrella package must include access to the Umbrella API.
API Authentication
Provide your Umbrella API credentials to the Umbrella for Government Token Authorization API to request an Umbrella API access token. An error response may indicate one of the following problems:
- Your API key may have expired. Update your API key and select a new expiration date.
- Your API key ID is incorrect or your API key secret is not valid.
- The format of the API request is not correct.
- Your request does not include the required request headers, or path and query parameters. For more information, see Authentication.
API Authorization
Provide your Umbrella API access token with every Umbrella API operation. An error response may indicate one of the following problems:
- Your Umbrella API access token has expired. Generate a new Umbrella API access token.
- Your access token does not include the scopes and permissions (Read Only or Read/Write) for the specific API endpoint.
- The format of your API request is not correct.
- Your request does not include the required request headers, or path and query parameters.