Error Codes

Public Access and Email Resource APIs use the actual HTTP status for failures. Successful responses return business data directly; they are not wrapped in success, code, message, or data fields.

Error response format

All documented errors use:

{
  "error": "invalidParameter",
  "message": "One or more parameters are invalid."
}

error is the stable value for application branching.
message is human-readable context for logging and troubleshooting.
Use the HTTP status as the request result. Do not look for a body-level code or success field.

Error values

HTTP status	`error`	Meaning
400	`invalidParameter`	A required value is missing, malformed, too long, or outside its accepted range.
401	`invalidCredential`	Basic credentials or the Application access token are missing, invalid, or expired.
403	`invalidContext`	The token or `userId` cannot resolve the required Application and End User context.
403	`insufficientScope`	The token is valid but is not an Application-scoped token.
404	`emailNotFound`	The Email slug cannot be resolved or the Email does not belong to the requested user.
405	`methodNotAllowed`	The path exists but does not support the supplied HTTP method.
500	`emailQueryFailed`	An unexpected Email Resource query or mutation failure occurred.
500	`serverError`	An unexpected non-Email server failure occurred, such as token creation failure.

Access API errors

`POST /access/token`

HTTP status	`error`	Typical cause
401	`invalidCredential`	Missing or malformed Basic Auth, or invalid credentials.
500	`serverError`	Token creation failed because of an unexpected server error.

Authentication failures intentionally use the same response so callers cannot distinguish a missing Client ID from an incorrect Client Secret:

{
  "error": "invalidCredential",
  "message": "The credential or access token is invalid or expired."
}

`POST /access/code`

HTTP status	`error`	Typical cause
400	`invalidParameter`	Missing or invalid JSON body, `userId`, `name`, `email`, `phone`, email format, or field length.
401	`invalidCredential`	Missing, malformed, invalid, or expired Application access token.
403	`insufficientScope`	The supplied token is not Application-scoped.

Email resource API errors

The following rules apply to all /resource/email operations:

HTTP status	`error`	Typical cause
400	`invalidParameter`	Invalid `userId`, request body, name, subject, pagination, or `extra` size.
401	`invalidCredential`	Missing, malformed, invalid, or expired Application access token.
403	`invalidContext`	Application context is unavailable, or the `userId` does not exist for an operation that requires it.
403	`insufficientScope`	The supplied token is not Application-scoped.
404	`emailNotFound`	The Email slug is unknown or is outside the requested End User scope.
500	`emailQueryFailed`	An unexpected query, ID resolution, create, update, delete, or copy failure occurred.

POST /resource/email may create a previously unknown userId. List, detail, update, delete, and copy operations require the End User context to exist.

Examples:

{
  "error": "emailNotFound",
  "message": "Email not found."
}

{
  "error": "emailQueryFailed",
  "message": "Email query failed."
}

Validation errors

A missing body or malformed JSON returns HTTP 400:

{
  "error": "invalidParameter",
  "message": "Request body is invalid."
}

Field validation messages may be more specific, for example:

userId is required
userId can only contain letters, numbers, underscores, and hyphens
name must not exceed 200 characters
email format is invalid
email must not exceed 200 characters
phone must not exceed 50 characters
name must not exceed 64 characters
pageNo must be positive and pageSize must be between 1 and 100

Recovery guidance

HTTP status	Recommended action
400	Correct the request before retrying.
401	Obtain or provide a valid Application access token, then retry.
403	Check token scope, Application ownership, and the supplied `userId`.
404	Check the public Email slug and End User scope; do not retry unchanged input.
405	Use the HTTP method defined by the endpoint.
500	Retry with bounded backoff. If failures continue, log the endpoint and response for support.