# 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:

```json
{
  "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 |
|---|---|---|---|
| <a id="invalid_parameter"></a>`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. |
| <a id="tenant_refused"></a>`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. |
| <a id="spec_invalid"></a>`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. |
| <a id="spec_unreadable"></a>`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. |
| <a id="policy_denied"></a>`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. |
| <a id="policy_unavailable"></a>`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. |
| <a id="dispatch_failed"></a>`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. |
| <a id="quota_exceeded"></a>`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. |
| <a id="no_acting_tenant"></a>`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. |
| <a id="isolation_refused"></a>`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. |
| <a id="no_such_submission"></a>`no_such_submission` | 404 | You have no submission with this ID. | Check the ID that `submit` returned. |
| <a id="no_such_artifact"></a>`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. |
| <a id="no_such_route"></a>`no_such_route` | 404 | No operation exists at this address. | Check the path against the API reference. |
| <a id="method_not_allowed"></a>`method_not_allowed` | 405 | This address does not accept that HTTP method. | Check the method against the API reference. |
| <a id="body_too_large"></a>`body_too_large` | 413 | Your request body is too large. | Send a smaller document. |
| <a id="malformed_request"></a>`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. |
| <a id="request_timeout"></a>`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. |
| <a id="provisioning_not_configured"></a>`provisioning_not_configured` | 503 | Installing images on servers is not available on this Tarsana deployment. | Contact Tarsana support if you need it. |
| <a id="image_endpoint_not_configured"></a>`image_endpoint_not_configured` | 503 | Image downloads are not available on this Tarsana deployment. | Contact Tarsana support if you need them. |
| <a id="provisioning_request_invalid"></a>`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. |
| <a id="not_provisionable"></a>`not_provisionable` | 409 | This submission has no finished build that can be installed. | Check its status, and try again when its build has succeeded. |
| <a id="provisioning_refused"></a>`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. |
| <a id="provisioning_failed"></a>`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. |
| <a id="create_not_configured"></a>`create_not_configured` | 503 | Creating servers is not available on this Tarsana deployment. | Contact Tarsana support if you need it. |
| <a id="not_creatable"></a>`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. |
| <a id="create_unavailable"></a>`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. |
| <a id="create_refused"></a>`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. |
| <a id="create_failed"></a>`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. |
| <a id="servers_not_configured"></a>`servers_not_configured` | 503 | Listing your servers is not available on this Tarsana deployment. | Contact Tarsana support if you need it. |
| <a id="no_such_provider"></a>`no_such_provider` | 404 | Tarsana does not support a provider with this name. | The response lists the providers you can use. |
| <a id="servers_unavailable"></a>`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. |
| <a id="no_such_server"></a>`no_such_server` | 404 | Your server list at this provider has no server with this ID. | Check the ID with `servers` and try again. |
| <a id="server_accounted_for"></a>`server_accounted_for` | 409 | Tarsana created this server, so you cannot delete it here. | Remove it with `decommission-server` instead. |
| <a id="destroy_failed"></a>`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. |
| <a id="decommission_not_configured"></a>`decommission_not_configured` | 503 | Decommissioning servers is not available on this Tarsana deployment. | Contact Tarsana support if you need it. |
| <a id="install_not_configured"></a>`install_not_configured` | 503 | Install commands are not available on this Tarsana deployment yet. | Try again later, or contact Tarsana support. |
| <a id="install_unavailable"></a>`install_unavailable` | 503 | Tarsana could not save the token for this command, so no command was issued. | Try again. |
| <a id="server_not_accounted_for"></a>`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`. |
| <a id="decommission_failed"></a>`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. |
| <a id="update_not_configured"></a>`update_not_configured` | 503 | Updating servers is not available on this Tarsana deployment. | Contact Tarsana support if you need it. |
| <a id="server_not_joined"></a>`server_not_joined` | 404 | No server with this name has joined your account, so there is nothing to update. | A server joins when its install command has run; use the name `create-server` (its `action_id`) or `install-command` gave it. |
| <a id="no_release"></a>`no_release` | 409 | The release channel you named carries no release a server would accept right now, so there is nothing to update to and nothing was sent. | Name another channel, or ask Tarsana support to publish a release. |
| <a id="release_moved"></a>`release_moved` | 409 | Your release channel now carries another version than the one you asked for, so nothing was sent to your server. | Check the version in the response and ask again. |
| <a id="update_failed"></a>`update_failed` | 502 | The release was refused when Tarsana tried to send it to your server, so nothing reached the server. | Contact Tarsana support. |
| <a id="update_unavailable"></a>`update_unavailable` | 503 | Tarsana could not send the update or read its outcome right now, so nothing reached your server. | Try again later; asking again sends the update. |
| <a id="no_update_requested"></a>`no_update_requested` | 404 | No update of this server has been requested. | Ask for one with `request-update`. |
| <a id="credentials_not_configured"></a>`credentials_not_configured` | 503 | Storing provider credentials is not available on this Tarsana deployment. | Contact Tarsana support if you need it. |
| <a id="vault_unavailable"></a>`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. |
| <a id="unauthenticated"></a>`unauthenticated` | 401 | Your request has no credential, or one that Tarsana does not recognise. | Sign in with `login`, or send a valid access token. |
| <a id="forbidden"></a>`forbidden` | 403 | Your role does not allow this operation. | The response names the roles that do; ask for a credential with one of them. |
| <a id="audit_unavailable"></a>`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. |
| <a id="surface_fault"></a>`surface_fault` | 500 | Something went wrong on our side. | Try again later, and contact Tarsana support if it keeps happening. |
| <a id="tenant_taken"></a>`tenant_taken` | 409 | This tenant ID is already taken. | Choose a different ID. |
| <a id="signup_refused"></a>`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. |
| <a id="signup_not_configured"></a>`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. |
| <a id="signup_rate_limited"></a>`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. |
| <a id="signup_delivery_failed"></a>`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. |
| <a id="rate_limited"></a>`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. |