API problems

Error response fields, problem types and actions to take when a request fails.

Error response body

HTTP errors return application/problem+json. The response follows RFC 9457 Problem Details. Its numeric status matches the HTTP status. Error responses use Cache-Control: no-store. HEAD errors have no response body.

HTTP 402 response body

{
  "type": "https://e.easycaptcha.to/insufficient_balance",
  "title": "Insufficient balance",
  "status": 402,
  "detail": "Your available credit is insufficient for this task.",
  "instance": "request_01m40t5ag0e008000000000005",
  "code": "insufficient_balance",
  "request_id": "request_01m40t5ag0e008000000000005"
}

Field	Type	Meaning
`type`	string, URI	Stable machine identifier, such as https://e.easycaptcha.to/insufficient_balance.
`title`	string	Human-readable summary. Do not use it to select program behavior.
`status`	integer	HTTP status. Absent in an embedded task error.
`detail`	string	Explanation of this particular failure.
`instance`	request TypeID	Identifier for this occurrence, suitable for support. It is not a lookup URL.
`code`	string	Short problem identifier.
`request_id`	request TypeID	The same value as instance.

Handling failures

Match type for program behavior. Ignore unknown extension fields and fall back to the HTTP status for an unknown problem type. Keep request_id for support.

The stable type URL redirects to its documentation. Opening it manually is useful; clients should not fetch type or instance values automatically.

A successful task lookup can return HTTP 200 with status="failed" and an embedded problem in error. That problem has the same fields except numeric status. The task's status remains a lifecycle string.

A lost connection with no response is a transport failure. It has no Problem Details body and does not prove that a write failed. Avoid automatically repeating task submissions after an ambiguous timeout.

Problem types

Code	HTTP status	Meaning
`invalid_request`	400	A field, identifier, query parameter or JSON body is invalid.
`invalid_credentials`	401	The API key is absent, invalid or revoked.
`insufficient_balance`	402	Available credit cannot cover the requested task.
`forbidden`	403	Your account does not have permission for this operation or package.
`account_suspended`	403	The account is suspended.
`not_found`	404	The route or resource is unavailable. Private resources owned by another account also return this status.
`task_not_found`	404	The task is unknown, belongs to another account or is no longer retained.
`task_expired`	404	The task has passed its availability window.
`method_not_allowed`	405	The route does not accept this HTTP method.
`conflict`	409	The operation conflicts with the resource's current state. An example is changing previously recorded feedback.
`task_failed`	409	The requested operation cannot proceed because the task failed. A task snapshot can also carry this problem inside error.
`payload_too_large`	413	The request body exceeds the endpoint's size limit.
`unsupported_media_type`	415	The request uses a Content-Type the endpoint does not accept.
`rate_limited`	429	A request rate or account concurrency limit was reached.
`internal_error`	500	The service encountered an unexpected error.
`bad_gateway`	502	The API could not obtain a usable response from a dependency.
`service_unavailable`	503	The service or a required dependency cannot currently serve the request.
`gateway_timeout`	504	The request exceeded a gateway waiting deadline.

API problems

Error response body

Handling failures

Problem types

Build your next integration with easycaptcha.