Resolve API Errors

Every error answered by the Resolve API is an RFC 9457 Problem Details document, Content-Type: application/problem+json:

{
  "type": "https://docs.wordlift.io/problems/dataset_not_supported",
  "title": "Dataset not supported",
  "status": 422,
  "instance": "/accounts/12345/resolve",
  "code": "dataset_not_supported",
  "dataset_uri": "x://y",
  "supported": ["wikidata://public", "wordlift://dataset/me", "inline"]
}

code is the stable identifier to compare on, and type is the page under https://docs.wordlift.io/problems/ describing it. detail is a sentence when the engine has one. Extension members carry what the engine knows about the failure and are listed on each code's page. Responses with an error status cost no credits.

The exception is the 429 the gateway answers when the account's monthly allowance is spent: its body is text/plain and the X-RateLimit-* headers describe the limit and when it resets. The engine's own 429 (too_many_requests) is Problem JSON with Retry-After. Where a retry time is given, the Retry-After header is authoritative.

Codes

HTTP status	code	Meaning
401	unauthorized	The request carried no WordLift key, an empty one, or one the account service does not recognise
422	invalid_request	The request body does not match the schema: a required field is missing, a value has the wrong type, or text is empty or longer than 100,000 characters
422	invalid_span	A mention you sent does not lie in text as written: the characters between start and end are not the mention's text, or the offsets fall outside the text
422	invalid_identity	A candidate id is not in a form the engine accepts
422	dataset_not_supported	dataset_uri names a world the engine does not serve, lists a world twice, or is empty
422	dataset_required	dataset_uri is inline but the request carries no dataset object
422	invalid_dataset	The inline dataset could not be read: an entity without an id or name, a field of the wrong type, or more than 5,000 entities
422	unknown_include	include lists a value the engine does not know
422	candidates_not_supported	A mention carries candidates while the request resolves against a user dataset (wordlift://dataset/me or inline)
429	too_many_requests	The replica serving your request has its limit of requests in flight and waiting, so this one was refused before any work was done
503	dataset_warming	Your knowledge graph is being read for the first time in a while
502 or 503	dataset_unavailable	With status 502: the knowledge graph named in dataset_uri could not be read from its source
404	not_found	The requested path does not exist
500	internal_error	The engine failed while handling the request
502	upstream_error	A service the engine depends on answered with an error while your request was handled
503	unavailable	The engine cannot serve requests at the moment, typically while starting
504	upstream_timeout	A service the engine depends on did not answer in time
any	error	An error without a more specific code; the HTTP status carries the meaning

Retrying

Nothing is resolved or charged when the status is an error, so a 429, 502 or 503 can be retried after the seconds given. The open clients do not retry on their own: a request that timed out on the client side may still have been served and metered, so the retry policy is yours.