# Errors

Tallymark uses standard HTTP status codes to tell you whether a request
worked. `2xx` codes mean it worked, and `4xx` codes mean it failed.
Errors you can handle in code include a `code`. Each endpoint lists the
errors it can return.

### HTTP status codes

- `200` OK: everything worked.
- `201` Created: the record was created.
- `400` Bad Request: the request couldn't be processed.
- `401` Unauthorized: the API key is missing, invalid, or revoked.
- `402` Payment Required: the payment or refund failed.
- `403` Forbidden: the API key is read only, or the account must verify
  its email first.
- `404` Not Found: the record doesn't exist or was deleted.
- `409` Conflict: the invoice can't be paid or refunded right now.
- `422` Unprocessable Content: a field is missing or invalid.
- `429` Too Many Requests: you made more than 300 requests in 5
  minutes, or the account can't send email right now.

### Error codes

- `request_failed`: the request couldn't be processed.
- `api_key_missing`: the request has no API key.
- `api_key_invalid`: the API key is invalid or revoked.
- `api_key_read_only`: the API key is read only and can't make POST
  requests.
- `api_version_unsupported`: the `Api-Version` header isn't a supported
  version.
- `amount_too_large`: the amount is more than what's left to pay or
  refund.
- `amount_too_small`: the amount is below the minimum card charge for
  the currency.
- `payment_method_not_found`: the payment method isn't one of the
  client's cards.
- `payment_failed`: the card was declined or the payment failed.
- `account_not_verified`: the account must verify its email before
  sending invoices or charging cards.
- `already_paid`: the invoice is already paid.
- `stripe_not_connected`: the account hasn't connected Stripe.
- `no_payment_method`: the client has no card on file.
- `nothing_to_refund`: the invoice has no payments left to refund.
- `refund_failed`: the refund failed at the payment processor.
- `too_many_emails`: the account hit its email limit and can't send
  email right now.
- `invoice_void`: the invoice is void.
- `invoice_finalized`: the invoice is no longer a draft.
- `subscription_draft`: the subscription is a draft.
- `subscription_ended`: the subscription has generated all of its
  `number_of_invoices`.

## The error object

- `message` (string): What went wrong, written for people.
- `code` (string): A short string for errors you can handle in code. See [error codes](#error-codes).

```json
{
  "message": "This invoice is already paid.",
  "code": "already_paid"
}
```

## The validation error object

- `message` (string): The first validation error, written for people.
- `errors` (object): The error messages for each invalid field, by field name.

```json
{
  "message": "The name field is required.",
  "errors": {
    "name": [
      "The name field is required."
    ]
  }
}
```