Errors

Corteksa uses standard HTTP status codes and a consistent JSON error shape, so you can handle failures the same way across every endpoint.

Error shape

{
  "statusCode": 403,
  "message": "You do not have permission to perform this action",
  "error": "Forbidden"
}

Validation errors return an array of messages:

{
  "statusCode": 400,
  "message": ["email must be an email", "name should not be empty"],
  "error": "Bad Request"
}

Status codes

Auth: 401 vs 403

• 401 = "I don't know who you are" — the credential is missing or invalid.
• 403 = "I know who you are, but you can't do this" — the permission/scope or access level (A > G > M > D) forbids it.

The 404 that's really a 403

Some resources (a chat or record outside your scope) are masked as 404 rather than 403, so you can't probe for things you can't see. If you're sure it exists, your access level is too low — see Authorization.

Handle errors well

• Parse message (string or array) for a user-facing reason.
• Retry 429 and 5xx with exponential backoff; never retry 4xx blindly.
• Treat 401 as "refresh and retry once", then send the user to log in.