Template Docs Commerce APIs Tools
Get Started
Get Started

Responses & Error Handling

In general, Squarespace APIs use standard HTTP response codes. Successful requests are met with one of the following statuses:

  • 200 OK: Your request succeeded.
  • 201 Created: Your request to create a new resource succeeded. The response body includes the new object.
  • 204 No Content: Your request succeeded and there is no data in the response.

Each endpoint supports one or more of these statuses. Please consult the documentation for the endpoints you want to use for those statuses.

With respect to response bodies, all JSON fields in a response, including any fields found in its child JSON objects, will exist for every call to the same endpoint, even if their values are occasionally null or including those fields seems to duplicate information. The goal is to relieve pressure on developers by removing the need to check for key existence in responses and for compatibility with unforgiving JSON deserializers expecting fields to be present in every response.

Errors

Squarespace APIs share a set of standard response codes and share a common error object formatting.

Error Objects

All errors include a standard error object. Each field will always be present, but values may be null as indicated.

{
  "type": "INVALID_REQUEST",
  "subtype": "MISSING_ARGUMENT", // nullable
  "message": "Expiration date is required",
  "details": { ... }, // nullable
  "contextId": "RUPSUSPOW"
}

The type and subtype fields are general purpose descriptors of the kind of error that occurred. The possible values of each are documented per endpoint.

The message field is intended for you, the developer, and shouldn't be displayed to an end-user or client. The message field will typically contain detailed debug information.

The details field is intended for machine-readable usage in generating user-friendly error messages for you and your users. Note that this field will be null unless otherwise specified.

The contextId field is intended for communicating a server error with Squarespace Customer Care. Please do not hesitate to report this context id along with any occurrences of 5xx-class errors.

4xx Client Errors

Codes in the 4xx range indicate that something is wrong with your request, or that your request cannot be completed due to a conflicting state that can be avoided through further action. The information you receive in the response provides some level of detail to help you debug.

  • 400 Bad Request: We could not accept your request, probably because of malformed syntax, a missing argument, or an invalid argument.
  • 401 Unauthorized: We could not accept your request because you did not include your API key or because your key is invalid or expired.
  • 403 Forbidden: We could not accept your request because the included API key is not scoped for access to the specified endpoint. A new key with proper scoping is required.
  • 404 Not Found: The resource could not be found.
  • 405 Method Not Allowed: You attempted to access a resource with an unsupported method.
  • 409 Conflict: Your request either conflicted with another request, likely due to simultaneous requests competing for the same resource, or conflicted with the current state of a resource, which may be resolved by modifying the resource and trying again, if desired.
  • 429 Too Many Requests: Your application issued too many requests in a short period of time.

5xx Server Errors

Any errors in the 5xx range indicate a problem happened with Squarespace’s servers. Please report the issue and include the contextId you received in the response.