Draft a JSON error response for an invalid authentication token

What's really being asked

This question tests whether you can design a standardized, secure, and developer-friendly HTTP error response. The interviewer cares about your familiarity with RFC 7807 Problem Details, your ability to choose semantically correct status codes, and your judgment about what information is safe to expose to API consumers. Senior engineers are expected to treat error responses as part of the API contract, not as afterthoughts.

The full answer

First, the status code must be 401 Unauthorized because the request lacks valid authentication credentials. Do not use 403 Forbidden, which signals that authentication succeeded but the client lacks authorization. Second, the Content-Type should be application/problem+json per RFC 7807. Third, the JSON body should include the standard members: type, a URI that identifies the problem class such as https://api.example.com/errors/invalid-token; title, a short human-readable summary like Invalid Authentication Token; status, repeating the 401 code; detail, a specific actionable message such as The provided token has expired or is malformed. Please authenticate again to obtain a valid token; and instance, a URI reference to the specific occurrence for correlation in logs. Fourth, mention extension members only if they add value, such as a retry after hint or a documentation link. Fifth, explicitly state what you omit: never echo the invalid token, never include stack traces, internal file paths, or database details.

The mistakes people make

Candidates often confuse 401 with 403. They sometimes return 400 Bad Request, which is too generic for an auth failure. Another red flag is inventing a bespoke error envelope without referencing RFC 7807, such as a simple message string or an error code integer that lacks documentation. Echoing the submitted token back to the client is a security anti-pattern because the token may be logged by proxies or browsers. Returning a generic 500 Internal Server Error for an auth failure breaks client trust and prevents retries. Finally, vague detail messages like Authentication failed without next steps frustrate developers.

What usually comes next

How would you handle rate limiting on your token endpoint? What if the token is valid but expired, would you change the response? How do you version your error type URIs? Would you support problem details in XML or HTML as well? How do you correlate the instance URI with distributed tracing IDs?

A concrete example

HTTP 401 Unauthorized with Content-Type application/problem+json and body containing type set to https://api.example.com/errors/invalid-auth-token, title set to Invalid Authentication Token, status set to 401, detail set to The bearer token is expired or malformed. Re-authenticate at POST /auth/token to obtain a new token, and instance set to /logs/errors/550e8400-e29b-41d4-a716-446655440000. This tells the developer precisely what went wrong, why, and how to fix it, while keeping sensitive server state out of the response.