Error Responses

All Card Management API errors follow a consistent JSON shape:

{
  "success": false,
  "error": "Human-readable error message"
}

HTTP status codes

Status	Meaning	Typical cause
200	Success	Request completed normally
201	Created	Resource created (e.g. card issued, individual onboarded)
400	Bad Request	Validation failed (missing/invalid body fields, malformed payload)
401	Unauthorized	JWT missing, expired, signature invalid, or partner inactive
403	Forbidden	Partner authenticated but doesn't own the target resource
404	Not Found	Resource id doesn't exist or isn't visible in the partner's scope
409	Conflict	Resource already exists (e.g. duplicate clientCode)
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Upstream provider (IT-Card) failure or unexpected exception

Authorization failures

Scenario	Status	Error message
Missing Authorization header	401	Authentication required
JWT expired	401	Token expired
JWT signature invalid	401	Invalid token signature
iss does not match Partner.url	401	Unknown issuer
sub does not resolve to a known partner	401	Unknown partner
Partner status is not active	401	Partner not active
Partner authenticated but resource is out of scope	403	Forbidden or Resource not owned by partner

Validation failures

When the request body or query fails Joi validation, the response is shaped like:

{
  "success": false,
  "error": "ValidationError: \"email\" must be a valid email",
  "details": [{ "path": ["email"], "message": "\"email\" must be a valid email" }]
}

Validation is performed with abortEarly: false, so all errors are returned in a single response.

Upstream failures

When IT-Card or another upstream provider returns a non-2xx response, the card management API surfaces the upstream error code and message. Common cases:

Upstream error	Card Management API response
IT-Card card not found	404 with IT-Card's cardMask/message
IT-Card card locked	409 with restriction details
IT-Card 5xx	502 Bad Gateway or 500 Internal Server Error

If the card management API itself can't reach the upstream provider (network failure, DNS), the response is 503 Service Unavailable.