Error Handling

The Crowd.Credit API uses standard HTTP status codes and returns structured error responses to help you diagnose and handle issues.

HTTP Status Codes

Code	Meaning	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions
404	Not Found	Resource does not exist
409	Conflict	Resource conflict (e.g., duplicate)
422	Unprocessable Entity	Validation failed
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error

Error Response Format

{
  "success": false,
  "data": null,
  "message": "Validation failed",
  "errors": [
    {
      "field": "amount",
      "code": "INVALID_AMOUNT",
      "message": "Amount must be greater than 0"
    }
  ]
}

Common Error Codes

Authentication Errors

Code	Message	Resolution
MISSING_API_KEY	API key is required	Include X-API-Key header
INVALID_API_KEY	API key is not valid	Check your API key
KEY_REVOKED	API key has been revoked	Generate a new API key
INSUFFICIENT_PERMISSIONS	Key lacks required permission	Update key permissions

Validation Errors

Code	Message	Resolution
INVALID_ADDRESS	Ethereum address is not valid	Provide a valid checksummed address
INVALID_AMOUNT	Amount is out of valid range	Check minimum/maximum amounts
INVALID_TOKEN	Token is not supported	Use a supported token

Credit Errors

Code	Message	Resolution
INSUFFICIENT_CREDIT	Not enough available credit	Reduce amount or add collateral
CREDIT_FROZEN	Credit line is frozen	Resolve freeze condition
HEALTH_FACTOR_LOW	Health factor would drop below 1.0	Add collateral first

Rate Limit Errors

When you hit a rate limit, the response includes headers to help you retry:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1709856060
Retry-After: 30

Wait for the number of seconds specified in the Retry-After header before retrying.

Best Practices

1. Always check success field -- Don't assume a 200 means success
2. Handle rate limits gracefully -- Implement exponential backoff
3. Log error codes -- Error codes are stable identifiers for programmatic handling
4. Don't expose raw errors to users -- Map error codes to user-friendly messages

Next Steps

• Set up authentication
• Browse endpoints