​
API Error Handling

This document outlines the standard error responses and status codes used in the StableStack API. All error responses follow a consistent format to help you handle errors gracefully in your application.

​
Error Response Format

All error responses follow this JSON structure:

{
    "status":"failed",
    "message":"internal error",
    "error": {
        "code": "ERROR_CODE",
        "message": "Human readable error message",
        "details": {} // Optional additional error details
    }
}

​
HTTP Status Codes

​
4xx Client Errors

Status CodeDescription
400Bad Request - The request was malformed or contained invalid parameters
401Unauthorized - Authentication is required or failed
403Forbidden - The request was understood but refused
404Not Found - The requested resource does not exist
409Conflict - The request conflicts with the current state of the resource
422Unprocessable Entity - The request was well-formed but contained semantic errors
429Too Many Requests - Rate limit exceeded

​
5xx Server Errors

Status CodeDescription
500Internal Server Error - An unexpected error occurred on the server
502Bad Gateway - The server received an invalid response from an upstream server
503Service Unavailable - The server is temporarily unable to handle the request
504Gateway Timeout - The server did not receive a timely response from an upstream server

​
Common Error Codes

​
Authentication Errors (401)

Error CodeDescription
INVALID_TOKENThe provided authentication token is invalid or expired
MISSING_TOKENNo authentication token was provided
INVALID_CREDENTIALSThe provided credentials are incorrect

​
Validation Errors (400, 422)

Error CodeDescription
INVALID_PARAMETEROne or more request parameters are invalid
MISSING_REQUIRED_FIELDA required field is missing from the request
INVALID_FORMATThe request data format is invalid

​
Resource Errors (404)

Error CodeDescription
RESOURCE_NOT_FOUNDThe requested resource does not exist
ENDPOINT_NOT_FOUNDThe requested API endpoint does not exist

​
Rate Limiting (429)

Error CodeDescription
RATE_LIMIT_EXCEEDEDToo many requests in a given time period
QUOTA_EXCEEDEDAPI quota has been exceeded

​
Best Practices

  1. Always check the status code first to determine if the request was successful
  2. Handle rate limiting by implementing exponential backoff
  3. Log error details for debugging purposes
  4. Implement retry logic for 5xx errors

​
Rate Limiting

The API implements rate limiting to ensure fair usage and system stability. Rate limits are applied per API key and are reset every minute.

  • Standard: 60 requests per minute

When rate limited, you’ll receive a 429 status code with the following response:

{
    "status":"failed",
    "message":"Rate limit exceeded. Please try again in 60 seconds.",
    "error": {
        "code": "RATE_LIMIT_EXCEEDED",
        "message": "Rate limit exceeded. Please try again in 60 seconds.",
        "details": {
        "retry_after": 60,
        "limit": 60,
        "remaining": 0
        }
    }
}