Error Codes

All API errors return a consistent JSON structure with an error code, message, and HTTP status code.

Error Response Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of what went wrong",
    "statusCode": 400
  }
}

Error Codes Reference

Client Errors (4xx)

Code	Status	Description
VALIDATION_ERROR	400	Request body or parameters are invalid
UNAUTHORIZED	401	Missing or invalid API key
FORBIDDEN	403	API key lacks permission for this operation
NOT_FOUND	404	Resource does not exist
CONFLICT	409	Resource already exists or version conflict
RATE_LIMIT_EXCEEDED	429	Too many requests — see Rate Limits

Server Errors (5xx)

Code	Status	Description
INTERNAL_ERROR	500	Unexpected server error — contact support
SERVICE_UNAVAILABLE	503	Service temporarily down for maintenance
GATEWAY_TIMEOUT	504	Request timed out — try again

Troubleshooting

401 Unauthorized

• Verify your API key is correct and hasn't been revoked
• Ensure the Authorization header format is Bearer YOUR_API_KEY
• Check that the key hasn't expired

403 Forbidden

• Your API key may not have the required scope (read/write/admin)
• You may be trying to access a resource in a different project
• Generate a new key with the appropriate permissions

404 Not Found

• Verify the resource ID is correct
• The resource may have been deleted
• Check that you're using the correct API version (/api/v1/)

429 Rate Limited

• Check the Retry-After header for when to retry
• Implement exponential backoff in your client
• Consider upgrading your plan for higher limits

500 Internal Error

• This is a server-side issue — your request is likely valid
• Retry the request after a brief delay
• If the error persists, contact support@onflowstack.com with the request details