Errors

Every portfolio endpoint returns errors via the standard project envelope (internal/http/response.JSON). Unlike the TradingView UDF surface, there is no UDF-style root-level error — portfolio is a normal authenticated REST API.

Error envelope

{
  "message": "<human-friendly summary>",
  "errors":  [{ "field": "<path>", "message": "<rule>" }]
}

errors[] is populated for validation failures. Other failures (404, 500) carry only message.

Content-Type: application/json always.

Status code map

There is no 403 in this module. "Not yours" is 404 by design.

Common 400 messages

These all surface from the request-decode layer (handlerutil.DecodeAndValidate) before any service code runs:

Per-endpoint quick lookup

Validation rule sources

The struct tags drive the bulk of validation. Examples from trades/types.go:

type AddTradeRequest struct {
    CompanyID    string  `json:"companyId"    validate:"required,uuid"`
    Type         string  `json:"type"         validate:"required,oneof=BUY SELL"`
    Quantity     int     `json:"quantity"     validate:"required,min=1"`
    PricePerUnit float64 `json:"pricePerUnit" validate:"required,gt=0"`
    TotalAmount  float64 `json:"totalAmount"  validate:"required,gte=0"`
    TradedAt     string  `json:"tradedAt"     validate:"required,iso8601"`
    Notes        *string `json:"notes"        validate:"omitempty,max=500"`
    // ...
}

Beyond struct tags, three layers of business validation kick in within services:

1. Trade fee math — completeTradeFees + computedTradeTotal reject totalAmount deviation > NPR 1.
2. Sell quantity check — holdings.CurrentUnitsForHolding rejects oversell with 422.
3. Type-specific corporate-action validation — validateCorporateAction enforces "BONUS needs qty>=1", "RIGHT_ISSUE needs price if qty>0", etc.

Soft warnings vs errors

Some "wrong" inputs are accepted with a warning rather than rejected:

These are deliberate UX calls. The server holds opinions about what's plausible but doesn't reject straight-line user data unless the FIFO math would actually be wrong.

Examples

$ curl -i -H "Authorization: Bearer $JWT" \
    "$BASE/portfolios/not-a-uuid"
HTTP/1.1 400 Bad Request
Content-Type: application/json
{"message":"Invalid id format"}

$ curl -X POST -i -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
    -d '{"companyId":"...","type":"BUY","quantity":10,"pricePerUnit":100,"cgtAmount":50,"totalAmount":1000,"tradedAt":"2026-04-01T00:00:00.000Z"}' \
    "$BASE/portfolios/$PID/trades"
HTTP/1.1 400 Bad Request
{"message":"cgtAmount is only valid on SELL trades"}

$ curl -X POST -i -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
    -d '{"companyId":"...","type":"BUY","quantity":100,"pricePerUnit":1250.00,"totalAmount":99999.00,"tradedAt":"2026-04-01T00:00:00.000Z"}' \
    "$BASE/portfolios/$PID/trades"
HTTP/1.1 400 Bad Request
{"message":"totalAmount mismatch: expected 125481.25"}

# Portfolio holds 50 units of NABIL; try to sell 100
$ curl -X POST -i ... -d '{"type":"SELL","quantity":100,...}' "$BASE/portfolios/$PID/trades"
HTTP/1.1 422 Unprocessable Entity
{"message":"SELL quantity exceeds current holding (50 units)"}

# The portfolio exists, but it belongs to another customer
$ curl -i -H "Authorization: Bearer $JWT" \
    "$BASE/portfolios/0192d4e5-6f7a-7b8c-9d0e-1f2a3b4c5d6e"
HTTP/1.1 404 Not Found
{"message":"Portfolio not found"}

Implementation

• Envelope: internal/http/response/response.go
• Decode + validate: internal/http/handlerutil
• Validator tags: registered in internal/http/validator
• Domain-specific errors: response.NewValidation, response.NewNotFound, response.NewStatus(http.StatusUnprocessableEntity, ...)