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 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 not valid.
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.
500	Server Error	Something went wrong on our end.

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.

Retrying

500 responses and network failures are worth retrying with backoff. 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.