Error Responses and Status Codes Reference

Every error response from the CA Colombia API returns a JSON body containing at least an error field with a human-readable message. Many errors also include a code field that identifies the specific failure condition, and validation errors add a details array with field-level information. You should always check both error and code when building error-handling logic in your application.

Error Response Shape

{
  "error": "Unauthorized",
  "code": "INVALID_TOKEN"
}

For validation failures, a details array is included alongside the error field:

{
  "error": "Invalid form of body",
  "details": [
    {
      "path": ["firstNames"],
      "message": "First name too short"
    }
  ]
}

HTTP Status Codes

The API uses standard HTTP status codes to communicate the outcome of every request. The table below describes what each code means in the context of CA Colombia.

Status	Meaning
`200`	The request succeeded and a response body is returned.
`201`	The request succeeded and a new resource was created.
`304`	Not Modified — the resource was already in the requested state and no change was made.
`400`	The request body or query parameters are invalid or malformed.
`401`	Unauthenticated — no valid session cookie was found or the token is invalid.
`403`	Forbidden — your session is valid, but you do not have the required permissions.
`404`	The requested resource was not found.
`409`	Conflict — for example, your character limit has been exceeded.
`429`	Rate limited — you have exceeded the allowed number of requests for this window.
`500`	Internal server error — an unexpected failure occurred on the server.

Authentication Error Codes

When a 401 or 403 response is returned, the code field contains a machine-readable identifier. Use these codes to distinguish between different authentication failure states and respond accordingly in your application.

Code	HTTP Status	Meaning
`UNAUTHENTICATED`	`401`	No session cookie was present on the request.
`INVALID_TOKEN_STRUCTURE`	`401`	The session cookie is present but its format is malformed.
`FAILED_TOKEN_UID_PARSE`	`401`	The user ID encoded in the token could not be decoded.
`INVALID_TOKEN`	`401`	The token was not found in the database — it may be expired or compromised.
`FAILED_TOKEN_UID_MISSMATCH`	`401`	The user ID embedded in the token does not match the token record.
`USER_NOT_FOUND`	`401`	The token is structurally valid but the associated user no longer exists.
`FAILED_TOKEN_PARSE_MISSMATCH`	`401`	The access token and refresh token could not both be parsed during a renewal attempt.
`MISSING_FULL_PERMISSIONS`	`403`	Your account is missing all of the required permissions for this endpoint.
`MISSING_PARTIAL_PERMISSIONS`	`403`	Your account is missing at least one of the required permissions for this endpoint.
`FAILED_TOKEN_RENEWAL`	`401`	Your session token was expired and the server could not refresh it using your refresh token.
`FAILED_TOKEN_PARSING`	`401`	The token could not be parsed — catch-all for unexpected token errors.

When INVALID_TOKEN is returned, the API automatically clears your session cookies. You will need to re-authenticate before making further requests.

Validation Errors

When you submit a request body that fails schema validation, the API returns a 400 response with "error": "Invalid form of body" and a details array. Each entry in the array corresponds to a specific field that failed validation. Example — creating a character with a missing field:

{
  "error": "Invalid form of body",
  "details": [
    {
      "path": ["firstNames"],
      "message": "First name too short"
    },
    {
      "path": ["dob"],
      "message": "Invalid dob"
    }
  ]
}

Each object in details contains:

path — an array of strings indicating which field or nested key failed. For top-level fields this is a single-element array, e.g. ["firstNames"].
message — a human-readable description of why the field failed validation.

Iterate over the details array to surface field-specific messages directly in your UI, rather than displaying the top-level error string alone.

Other Common Error Responses

Error message	Typical status	When it occurs
`"The resource was not found"`	`404`	A generic resource look-up returned nothing.
`"Unknown User"`	`404`	The requested user ID does not exist.
`"Unknown Character"`	`404`	The requested character ID does not exist.
`"User Max Character Limit Exceeded"`	`409`	You have reached the maximum number of characters allowed on your account.
`"Internal Server Error"`	`500`	An unexpected error occurred. Check the optional `message` field for details.

500 responses may include a message field with additional context, but this is not guaranteed. Do not rely on its presence in production error-handling code.

Get Started

Core Concepts

Guides

Reference

Error Responses and Status Codes Reference

Error Response Shape

HTTP Status Codes

Authentication Error Codes

Validation Errors

Other Common Error Responses

​Error Response Shape

​HTTP Status Codes

​Authentication Error Codes

​Validation Errors

​Other Common Error Responses

Error Response Shape

HTTP Status Codes

Authentication Error Codes

Validation Errors

Other Common Error Responses