Errors

When Tarsana cannot do what you asked, the answer has an HTTP status of 400 or higher and a JSON body with an error object in it:

{
  "error": {
    "code": "no_such_submission",
    "message": "One sentence that says what went wrong.",
    "detail": {
      "...": "more facts, when there are any"
    },
    "doc_url": "https://docs.tarsana.io/api/errors#no_such_submission"
  }
}

Field	What it is
`code`	A code from the table below. Your program should act on the code, never on the message.
`message`	A sentence for a person to read. It can change at any time.
`detail`	More facts about this refusal, when there are any: which check failed, which roles would be allowed, how long to wait.
`doc_url`	A link to the code's entry on this page.

Error codes

Code	HTTP	What happened	What to do
`invalid_parameter`	400	A value in your request does not have the expected format, for example a submission ID that is not a spec hash.	Check the value against the field's description and try again.
`tenant_refused`	400	This tenant ID is not allowed, or is not in the expected format.	Use a different ID made of lower-case letters, digits, dots, dashes and underscores.
`spec_invalid`	400	Your spec does not match the spec format.	Fix each problem listed in the response, at the path it gives, and send the spec again.
`spec_unreadable`	400	The request has no spec, or the spec could not be parsed.	Send the spec as valid JSON, or as a YAML or JSON file on the command line.
`policy_denied`	400	Your spec breaks one or more rules of the security policy.	Change your spec to meet each rule listed in the response, then submit it again.
`policy_unavailable`	503	Your spec could not be checked against the security policy, so it was not accepted.	This is a problem on our side: try again later, or contact Tarsana support.
`dispatch_failed`	502	Your submission was stored, but its build could not be started.	Submit the same spec again to start it; if your tenant is over a quota, you get `quota_exceeded` instead.
`quota_exceeded`	429	Your submission was stored, but no build was started because your tenant is over a quota.	The response shows each limit and your usage; submit again when you are back under the limit.
`no_acting_tenant`	400	Your request does not say which tenant you are acting for.	Send your tenant ID in the `X-Tarsana-Tenant` header, or with `--as` on the command line.
`isolation_refused`	403	This address belongs to a tenant ID you do not have access to.	Check the tenant ID in the address and in your request header.
`no_such_submission`	404	You have no submission with this ID.	Check the ID that `submit` returned.
`no_such_artifact`	404	This submission does not have that record yet.	The response says what state the build is in and what will produce the record.
`no_such_route`	404	No operation exists at this address.	Check the path against the API reference.
`method_not_allowed`	405	This address does not accept that HTTP method.	Check the method against the API reference.
`body_too_large`	413	Your request body is too large.	Send a smaller document.
`malformed_request`	400	Your request body is not valid JSON, or its Content-Length header is not a valid size.	Send the body as JSON, with a Content-Length that matches it.
`request_timeout`	408	Your request said a body was coming, but the body did not arrive in time.	Send the whole body with the request, and check that its Content-Length matches it.
`provisioning_not_configured`	503	Installing images on servers is not available on this Tarsana deployment.	Contact Tarsana support if you need it.
`image_endpoint_not_configured`	503	Image downloads are not available on this Tarsana deployment.	Contact Tarsana support if you need them.
`provisioning_request_invalid`	400	Your provisioning request is not valid: a field is missing, or a value is not supported.	Correct the request and send it again.
`not_provisionable`	409	This submission has no finished build that can be installed.	Check its status, and try again when its build has succeeded.
`provisioning_refused`	409	The provider cannot install this image in any of the ways your request allows.	The response says why and what you can change, because sending the same request again will not help.
`provisioning_failed`	502	The installation did not complete, for example because the provider returned an error.	The response says where it stopped and whether trying again can help.
`create_not_configured`	503	Creating servers is not available on this Tarsana deployment.	Contact Tarsana support if you need it.
`not_creatable`	409	Your spec has no `placement`, or one that cannot be read, so Tarsana does not know where to create the server.	Add a provider and a server type to the spec's `placement`, then submit it again.
`create_unavailable`	502	No server could be created with your stored credential at the provider in your spec's `placement`: none is stored, or it could not be used.	Check your credential with `provider-credential`, then try again.
`create_refused`	409	The provider refused to create the server, and nothing was created.	The response says why; fix the cause, then send the request again.
`create_failed`	502	The server creation did not complete, and a server may exist at the provider; the response names it if so.	Send the same `request_id` again: you get that server back, never a second one.
`servers_not_configured`	503	Listing your servers is not available on this Tarsana deployment.	Contact Tarsana support if you need it.
`no_such_provider`	404	Tarsana does not support a provider with this name.	The response lists the providers you can use.
`servers_unavailable`	502	Your server list could not be read with your stored credential: none is stored, the provider refused it, or the provider could not be reached.	Check your credential with `provider-credential`, then try again.
`no_such_server`	404	Your server list at this provider has no server with this ID.	Check the ID with `servers` and try again.
`server_accounted_for`	409	Tarsana created this server, so you cannot delete it here.	Remove it with `decommission-server` instead.
`destroy_failed`	502	The provider did not delete the server, and your request and its result are recorded.	Try again, or check the server at your provider.
`decommission_not_configured`	503	Decommissioning servers is not available on this Tarsana deployment.	Contact Tarsana support if you need it.
`install_not_configured`	503	Install commands are not available on this Tarsana deployment yet.	Try again later, or contact Tarsana support.
`install_unavailable`	503	Tarsana could not save the token for this command, so no command was issued.	Try again.
`server_not_accounted_for`	409	Tarsana cannot prove it created this server, so it does not decommission it.	If you want it gone, delete it with `destroy-server`.
`decommission_failed`	502	The decommission stopped at the step the response names, and that step is recorded.	Send the same request again to continue from there.
`credentials_not_configured`	503	Storing provider credentials is not available on this Tarsana deployment.	Contact Tarsana support if you need it.
`vault_unavailable`	503	Your provider credential could not be stored or read, because credential storage is not enabled for your tenant or is not working.	Contact Tarsana support.
`unauthenticated`	401	Your request has no credential, or one that Tarsana does not recognise.	Sign in with `login`, or send a valid access token.
`forbidden`	403	Your role does not allow this operation.	The response names the roles that do; ask for a credential with one of them.
`audit_unavailable`	503	Your audit trail could not be written or read.	If you made a change, it was carried out but is missing from the trail, so contact Tarsana support.
`surface_fault`	500	Something went wrong on our side.	Try again later, and contact Tarsana support if it keeps happening.
`tenant_taken`	409	This tenant ID is already taken.	Choose a different ID.
`signup_refused`	400	Your signup could not be completed: the link was already used or has expired, your identity was not confirmed, your email domain is not accepted, or this identity already has a login.	The response says which; start a new signup, or sign in with your existing login.
`signup_not_configured`	503	This way of signing up is not available on this Tarsana deployment.	Choose another way to sign up, or contact Tarsana support.
`signup_rate_limited`	429	Too many signups were started from your address, or a link was sent to this email address too recently.	Wait for the time given in the response, then try again.
`signup_delivery_failed`	502	Your signup link could not be sent, so nothing was created.	Start the signup again, or sign up with Google or LinkedIn instead.
`rate_limited`	429	You sent too many requests in a short time.	Wait for the number of seconds in `retry_after_seconds`, then try again.

View this page as Markdown