Errors - PCX Developer Docs

Error response format

All PCX services return errors in a consistent JSON envelope:

{
  "status": "error",
  "message": "Human-readable description of what went wrong"
}

Some services include an additional error field with a technical detail string (present mainly on 500 responses):

{
  "status": "error",
  "message": "An internal error occurred",
  "error": "NullPointerException at use_case line 42"
}

HTTP status codes

Code	Meaning	When it occurs
`200`	OK	Successful GET, PUT, PATCH, DELETE
`201`	Created	Successful POST that creates a resource
`204`	No Content	Successful DELETE with no response body
`207`	Multi-Status	Partial success (e.g. `target_type: both` notifications where one fails)
`400`	Bad Request	Missing required fields, invalid values, validation errors
`401`	Unauthorized	Missing, malformed, or expired auth credentials
`403`	Forbidden	Valid credentials but insufficient role/permission
`404`	Not Found	Resource does not exist
`409`	Conflict	Operation conflicts with current state (e.g. duplicate invite, deletion conflict)
`500`	Internal Server Error	Unhandled exception in the service

Success response format

Successful responses follow one of two shapes depending on the service: Standard envelope (most services):

{
  "status": "success",
  "message": "Operation description",
  "data": { ... }
}

Direct object (some older endpoints):

{
  "user_id": "...",
  "email": "...",
  ...
}

Decimal handling

Monetary values are stored as DynamoDB Decimal types and serialized to JSON as floats. Always treat amounts as number in your client — never as integers.

​Error response format

​HTTP status codes

​Success response format

​Decimal handling

Error response format

HTTP status codes

Success response format

Decimal handling