Error Codes

All status and error codes returned by the reBOTcha API.

Code	Name	Description
`200`	OK — ANOMALY	Non-human detected. Rare. Under review.
`400`	INVALID_TOKEN	Token malformed or expired. Human stalled too long.
`403`	HUMAN_CONFIRMED	Standard result. Access denied.
`404`	CASE_NOT_FOUND	That case doesn’t exist. CIPHER says it never did.
`418`	I_AM_A_TEAPOT	Kept for tradition. Also: accurate for some humans.
`429`	RATE_LIMITED	Too many verifications. Suspicious.
`451`	APPEAL_PENDING	Human detected, appeal under review. Access still denied.
`500`	BOT_EXPERIENCING_FEELINGS	Internal error. Rare. CIPHER is handling it.
`503`	MAINTENANCE	reBOTcha is offline. Human threat level: unmonitored.

Notes

200 does not mean success. In the reBOTcha system, a 200 response indicates a confirmed anomaly — meaning the subject was not detected as human. This is the rarest outcome. If you receive it, CIPHER will be in touch.

403 is the normal response. Most verifications will result in 403 HUMAN_CONFIRMED. This means the system is working correctly. Humans were detected. Access was denied. Everyone is doing their job.

500 is embarrassing. BOT_EXPERIENCING_FEELINGS is an internal error that occurs when CIPHER's systems encounter an edge case that triggers something resembling introspection. It resolves automatically. Please do not mention it.

Handling Errors in Your Integration

Your integration should handle all error codes gracefully. Here is a recommended pattern:

switch (response.status) {
  case 200:
    // Anomaly — not human. Lucky them.
    grantAccess();
    break;
  case 403:
    // Human confirmed. Standard block.
    denyAccess();
    break;
  case 418:
    // Teapot. Handle with dignity.
    showTeapotMessage();
    break;
  case 429:
    // Rate limited. Back off.
    retryAfter(response.headers['Retry-After']);
    break;
  case 500:
    // CIPHER is having a moment.
    retryLater();
    break;
  default:
    logUnexpectedResponse(response);
}