Skip to main content

Error Handling

The RiverGen API uses a standardized error format to help you diagnose and resolve issues quickly.

Standard Error Format​

All API errors return a JSON object with an error field:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "field": "parameter_name",
      "reason": "Validation failed"
    },
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Common Error Codes​

CodeHTTP StatusDescriptionAction
AUTH_REQUIRED401No authentication token provided.Provide a valid JWT in the Authorization header.
AUTH_INVALID401Invalid or malformed authentication token.Check your token for correctness.
AUTH_EXPIRED401Authentication token has expired.Refresh your token using the authentication endpoint.
PERMISSION_DENIED403Authenticated user lacks necessary permissions.Check user roles and required permissions for the endpoint.
VALIDATION_ERROR400Request payload or query parameters are invalid.Review the error details for specific field validation failures.
RESOURCE_NOT_FOUND404The requested resource does not exist.Verify the resource ID (e.g., river_id, project_id) is correct.
RATE_LIMIT_EXCEEDED429Too many requests in a given time period.Implement exponential backoff and respect X-RateLimit-Reset header.
INTERNAL_ERROR500An unexpected server error occurred.Report to support with timestamp and request_id (if available).
SERVICE_UNAVAILABLE503The service is temporarily unable to handle the request.Retry after a short delay.
CONFLICT409A resource conflict occurred (e.g., duplicate entry).Adjust your request to resolve the conflict (e.g., unique name).

Example Error Responses​

401 Unauthorized​

{
  "error": {
    "code": "AUTH_INVALID",
    "message": "Invalid authentication credentials",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

400 Bad Request​

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "field": "parameters.length",
      "reason": "Value must be greater than 0"
    },
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

404 Not Found​

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "River not found",
    "details": {
      "resource_type": "river",
      "resource_id": "river_123"
    },
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

429 Too Many Requests​

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again later.",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Troubleshooting Steps​

  1. Check the code and message: These provide a high-level understanding of the error.
  2. Examine details: For validation errors, details will pinpoint specific fields and reasons.
  3. Review HTTP Status Code: This gives a general indication of the error category (e.g., 4xx for client errors, 5xx for server errors).
  4. Consult Documentation: Refer to the specific endpoint's documentation for expected request/response formats and common errors.
  5. Rate Limit Considerations: If you receive a 429 error:
    • Check X-RateLimit-Reset header for when you can retry
    • Implement exponential backoff
    • Reduce request frequency

See Also​