Errors

Edit Square uses conventional HTTP response codes to indicate whether an API request succeeded or failed. In general:

• Codes in the 2xx range indicate success.
• Codes in the 4xx range indicate a problem with the request itself - a missing parameter, an invalid API key, an ID that doesn’t exist.
• Codes in the 5xx range indicate an error on our side. These are rare, and along with 429 they are the only ones worth retrying unchanged.

HTTP status codes

Code		Meaning
200	OK	Everything worked as expected.
201	Created	The entity was created.
400	Bad Request	The request was understood but could not be carried out.
401	Unauthorized	No API key was provided, or the key is unknown, revoked or expired. See authentication errors.
402	Payment Required	The team has run out of credits.
403	Forbidden	The key is valid but does not have access to this resource.
404	Not Found	The resource doesn’t exist, or your key can’t access it. The API deliberately doesn’t distinguish between the two.
422	Unprocessable Content	The request failed validation. The response lists the fields that failed.
429	Too Many Requests	Too many API key verifications are happening at once. Wait a moment and retry.
500	Server Error	Something went wrong on our end.
503	Service Unavailable	Your API key couldn’t be verified right now. This is temporary, so retry.

The error object

Every error response is a JSON object containing an error field, whose value is a human-readable sentence describing what went wrong. It is written for a developer reading a log, not for display to an end user. For everything except validation failures, error is the only field in the object:

{ "error": "Render not found" }

Validation errors

A 422 extends the object with two extra fields: a message string that summarises the failure on a single line (the problem itself when there is only one, a count when there are several), and a details array with one entry for each field that failed:

{
  "error": "Validation failed",
  "details": [
    {
      "field": "project_id",
      "message": "project_id: Project ID is required",
      "code": "too_small"
    }
  ],
  "message": "project_id: Project ID is required"
}

Each entry in details has:

Attribute		Description
field	string	The name of the parameter that failed, using dot notation for nested parameters. Set to unknown when the failure can’t be attributed to a single field.
message	string	A description of what is wrong with the value, prefixed with the field name.
code	string	The name of the validation rule that failed - too_small, invalid_type, and so on.

field is what makes a 422 worth surfacing to users: it identifies the parameter that needs fixing, so a form can highlight the offending input instead of showing the raw response.

Authentication errors

Every request is checked for a valid API key before anything else happens, and a request that fails the check gets one of these:

Code	error	What to do
401	Missing API key in Authorization header	Send the key as Authorization: Bearer <key>.
401	Invalid API key	The key is unknown, revoked or expired. Create a new one under API Keys in your account settings.
401	Retired API key. Create a new one in your Edit Square account.	Create a new key under API Keys and use that instead.
429	Too many requests. Try again in <n>s.	Wait the number of seconds in the Retry-After header, then retry.
503	Couldn't verify the API key. Try again shortly.	Verification is temporarily unavailable. Retry with backoff.

See Authentication for how to create a key.

Retrying

500 and 503 responses and network failures are worth retrying with backoff, and a 429 is worth retrying after a short wait. 401, 403, 404 and 422 are not - they describe a problem with the request, and the same request will fail the same way. A 402 means the team needs more credits before anything else will work.