Errors

Non-2xx responses return an error object:

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "requests.3.custom_id: 1 to 64 letters, digits, '_' and '-', unique in the batch",
    "retryable": false,
    "request_id": "req_6f1c0d9e2b7a4c3d8e5f1a2b"
  }
}

Field	Description
`type`	The error category. See statuses
`code`	A stable code to handle errors by. Codes are not renamed or reused
`message`	A human-readable description. Wording may change
`retryable`	Whether the identical request may succeed later
`request_id`	The request’s ID, for support
`action_url`	On `out_of_credit` only: the page to add credit

Every response includes a Request-Id header. Retryable errors may include Retry-After, in seconds.

Statuses

Status	Type	Meaning
400	`invalid_request_error`	Invalid request; `message` names the parameter
401	`auth_error`	No API key, a key that does not work, or a sign-in billed to no organization
403	`auth_error`, `invalid_request_error`	The key does not have access to what it called, or test mode’s 5 twins per organization per 24 hours are used
404	`invalid_request_error`	No such object for this key, or no such route
405	`invalid_request_error`	The route does not take that method
409	`idempotency_error`, `invalid_request_error`	An idempotency key conflict, or an object in the wrong status for the request
410	`invalid_request_error`	The twin’s content can no longer be downloaded
413	`invalid_request_error`	The file, or the request body, is too large
500	`api_error`	An unexpected failure; nothing was created or charged
503	`api_error`	Unavailable for a moment; retry after `Retry-After`

No request fails for lack of credit. A twin or batch the organization can’t cover is accepted and pauses until credit is added or other twins finish; see item errors.

Codes

The complete set of API error codes. For signing in, keys and organizations, see the account pages.

Code	Status	Retryable	Meaning
`missing_api_key`	401	no	No API key was sent
`invalid_api_key`	401	no	The API key is unknown, revoked or mistyped
`no_organization`	401	no	The sign-in is not billed to an organization; use an organization API key
`insufficient_scope`	403	no	The API key does not have access to what it called
`auth_unavailable`	503	yes	The API key could not be checked; nothing was created
`balance_unavailable`	503	yes	The balance could not be checked; nothing was created
`test_quota_exhausted`	403	no	Test mode: 5 twins per organization per 24 hours used; use a live key
`invalid_filename`	400	no	The file name is not one the upload takes
`invalid_end_user`	400	no	`end_user` is not 1 to 128 letters, digits, `.`, `_`, `:` and `-`
`parameter_invalid`	400	no	A parameter is missing or invalid; the message names it, such as `requests.3.file_id`
`parameter_unknown`	400	no	The request has a field the route does not take; the message names it
`json_invalid`	400	no	The body is not valid JSON
`unknown_api_version`	400	no	`Metaphi-Version` names no version this API serves
`body_invalid`	400	no	The request body could not be read
`file_empty`	400	no	The uploaded file is empty
`file_unsupported`	400	no	The file is not JSON, JSON Lines or UTF-8 text
`file_in_use`	409	no	The file is in a batch and cannot be deleted
`file_too_large`	413	no	The file is over 50 MiB, or 2 MiB in test mode. Split it and upload each part
`body_too_large`	413	no	The request body is over its route’s limit: 4 MiB for a batch, 64 KiB for any other JSON body
`idempotency_key_invalid`	400	no	The `Idempotency-Key` header is empty, too long or not printable ASCII
`idempotency_key_reused`	409	no	The `Idempotency-Key` was used with a different request in the last 24 hours
`idempotency_key_in_use`	409	yes	A request with the same `Idempotency-Key` is still being handled
`resource_missing`	404	no	No such object for this key’s organization and mode
`route_missing`	404	no	No such route
`method_not_allowed`	405	no	The route does not take that method
`twin_not_completed`	409	yes	The twin has not completed; its content is not ready
`twin_failed`	409	no	The twin failed and has no content
`content_expired`	410	no	The twin’s content can no longer be downloaded
`batch_already_ended`	409	no	The batch has ended
`batch_not_ended`	409	yes	The batch has not ended; its results are not ready
`webhook_url_invalid`	400	no	The webhook URL is not https, or not on a public host
`webhook_endpoint_limit`	400	no	The organization already has as many webhook endpoints as it may
`webhooks_unavailable`	503	yes	Webhooks are not available just now
`unavailable`	503	yes	The request could not be handled; nothing was created or charged
`internal_error`	500	yes	An unexpected failure; nothing was created or charged

Twin failures

A twin with status: failed has an error object, {type, code, message, retryable, action_url}, also set on its batch item and in the kennet.twin.failed event. Failed twins are not charged. Unsupported formats are refused at upload with 400 file_unsupported.

Code	Type	Retryable	Meaning
`not_text`	`run_error`	no	The trace is not JSON, JSON Lines or UTF-8 text

A twin fails only when its trace causes it. Errors on our side are retried automatically, and an exhausted balance pauses the twin.

Item errors

A batch item has an error object, {type, code, message, retryable, action_url}, when its status is failed, expired or paused. A failed item with a twin carries that twin’s failure. A request that fails before its twin is created sends kennet.batch_item.failed.

Code	Type	Status	Cause	Resolution
`out_of_credit`	`billing_error`	`paused`	The organization ran out of credit	Add credit at `action_url`; the item resumes by itself
`batch_expired`	`api_error`	`expired`	The batch expired before the request ended	Send the file in a new batch
`test_quota_exhausted`	`invalid_request_error`	`failed`	Test mode: 5 twins per organization per 24 hours used	Use a live key

Items cancelled before starting have status: cancelled and no error.

Getting started

Taskforge

Twin API

Deliveries API

Reference

Statuses

Codes

Twin failures

Item errors

​Statuses

​Codes

​Twin failures

​Item errors

Statuses

Codes

Twin failures

Item errors