Errors

List of status codes and error types you might encounter.

You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the error type and error message to figure out what has gone wrong and do some rudimentary debugging.

Error Types

Here is a list of the different categories of status codes returned by the UsageGuard API. Use these to understand if a request was successful.

Authentication Errors

Code	Description
MISSING_API_KEY	The UsageGuard API key is missing from the request. Ensure that you include your UsageGuard API Key in header `x-api-key`.
INVALID_API_KEY	The provided UsageGuard API key is invalid. Verify that you are using the correct API key.

Connection Errors

Property	Description
INVALID_CONNECTION_ID	The connection ID provided is invalid. Check that you are using the correct connection ID.
MISSING_CONNECTION_ID	The connection ID is missing from the request. Ensure that you include the connection ID in your request.
CONNECTION_NOT_FOUND	The specified connection could not be found. Verify that the connection ID is correct and that the connection exists.
CONNECTION_DISABLED	The specified connection is disabled. Check the connection settings and enable it if necessary.

Policy Errors

Code	Description
POLICY_NOT_FOUND	The specified policy could not be found. Verify that the policy ID is correct and that the policy exists.
REQUEST_BLOCKED_BY_POLICY	The request was blocked by a policy. Review the policies applied to the connection and adjust them if necessary.

Rate Limit Errors

Code	Description
CONNECTION_RATE_LIMIT_EXCEEDED	The connection has exceeded its rate limit. Reduce the number of requests or increase the rate limit for the connection.
END_USER_RATE_LIMIT_EXCEEDED	The end-user has exceeded their rate limit. Reduce the number of requests or increase the rate limit for the end-user.

Request Errors

Code	Description
REQUEST_TOO_LARGE	The request size is too large. Reduce the size of the request payload.
INVALID_REQUEST	The request is invalid. Check the request parameters and ensure they are correct.
MISSING_REQUIRED_FIELDS	The request is missing required fields. Ensure that all required fields are included in the request.

System Errors

Code	Description
CONFIGURATION_ERROR	There is a configuration error. Check your configuration settings and ensure they are correct.
INTERNAL_SERVER_ERROR	An internal server error occurred. This is a server-side issue, and you may need to contact support if it persists.

User Errors

Code	Description
MISSING_END_USER_ID	The end-user ID is missing from the request. Ensure that you include the end-user ID in your request.

Error Response

Whenever a request is unsuccessful, the UsageGuard API will return an error response with an error type and message. You can use this information to understand better what has gone wrong and how to fix it. Most of the error messages are pretty helpful and actionable.

Errors returned from providers are returned as is, so you can use the error message and error code to understand what went wrong.

Error Response

{
  "requestId": "traceid-ug-ltexted6fk3d3",
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "Policy type is required",
    "details": "The policy type cannot be null or empty. Please provide a valid policy type and try again.",
    "docUrl": "https://docs.usageguard.com/errors"
  }
}