Sign In

Error Handling

The Upstat API uses conventional HTTP status codes and returns detailed error information in a consistent JSON format.

Error Response Format

All errors are wrapped in an error object:

Error object fields:

Field Type Description
type string Error category (see Error Types below)
code string Specific error code for programmatic handling
message string Human-readable description
param string Parameter that caused the error (if applicable)
doc_url string Link to relevant documentation

Every error response includes a Request-Id header for debugging:

Request-Id: req_NffrFeUfNV2Hib

Include this ID when contacting support.

Error Types

Type Description Common Status
api_error Internal server error. Retry with exponential backoff. 500
authentication_error Invalid or missing API token 401
invalid_request_error Invalid parameters or resource not found 400, 404
rate_limit_error Too many requests. Check Retry-After header. 429
permission_error Valid token but insufficient permissions 403
idempotency_error Idempotency key reused with different parameters 409

HTTP Status Codes

Success codes:

Code Meaning When Used
200 OK Successful GET or PATCH request
201 Created Successful POST request (resource created)
204 No Content Successful DELETE request

Client error codes:

Code Meaning When Used
400 Bad Request Invalid parameters, missing required fields
401 Unauthorized Invalid or missing API token
403 Forbidden Valid token but insufficient permissions
404 Not Found Resource doesn’t exist
409 Conflict Idempotency key conflict
422 Unprocessable Entity Validation failed
429 Too Many Requests Rate limit exceeded

Server error codes:

Code Meaning When Used
500 Server Error Internal error (include Request-Id for support)
503 Service Unavailable Temporary outage (retry with backoff)

Error Codes

Authentication Errors

Code Message Solution
invalid_api_key Invalid API key provided Check token was copied correctly
expired_api_key API key has expired Regenerate or create new token
missing_api_key No API key provided Include Authorization: Bearer <token> header

Permission Errors

Code Message Solution
insufficient_permissions Token lacks required permission Edit token to add the needed permission
resource_access_denied Cannot access this resource Verify token has access to the project

Validation Errors

Code Message Solution
parameter_invalid Invalid value for parameter Check parameter format and constraints
parameter_missing Required parameter missing Include all required fields
parameter_unknown Unknown parameter provided Remove unrecognized fields

Resource Errors

Code Message Solution
resource_missing Resource not found Verify the resource ID exists
resource_already_exists Resource already exists Use a different identifier
resource_conflict Resource state conflict Check current state before updating

Idempotency Errors

Code Message Solution
idempotency_key_in_use Key reused with different parameters Use a unique key for each unique request

Rate Limit Errors

Code Message Solution
rate_limit_exceeded Too many requests Wait for Retry-After seconds

Handling Errors

Retry Strategy

For transient errors (500, 503, 429), implement exponential backoff:

Attempt Wait Time
1 1 second
2 2 seconds
3 4 seconds
4 8 seconds
5 16 seconds

For rate limit errors (429), always respect the Retry-After header.

Error Examples

400 - Invalid Parameter:

401 - Authentication Failed:

403 - Permission Denied:

404 - Resource Not Found:

409 - Idempotency Conflict:

429 - Rate Limited:

Response includes:

Retry-After: 30
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200