Error Response Status Codes

The Crezco Payables API uses HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.). Codes in the 5xx range indicate an error with our servers.

The following HTTP status codes are common across all Crezco Payables API endpoints

400 Bad Request - The data submitted to the endpoint was incorrect
403 Forbidden - The API Key could not be authenticated or does not allow access to a resource.
404 Not Found - The API endpoint you requested could not be found or you have requested a resource that does not exist
406 Not Acceptable - An invalid Crezco-Version header was provided. See Versioning below
409 Conflict - The request could not be processed because of conflict in the request
424 Failed Dependency - A downstream dependency has failed
429 Too Many Requests - You have called the API too many times in too short a period. Wait a while and try again
501 Not Implemented - You have called an endpoint for a feature in a pre-release version that is planned but may not support your edge case.
5XX - Something went wrong with our servers. Wait a while and try again (this is rare)

Error Response Body

Any API call that results in a non-success return code (4xx/5xx) will return a standardised error payload. This is a ProblemDetails structure as defined in RFC 7807

Type (string): A URI reference that identifies the problem type
Title (string): A short, human-readable summary of the problem type
Status (integer): The HTTP status code generated by the origin server for this occurrence of the problem.
Detail (string): A human-readable explanation specific to this occurrence of the problem.
Instance (string): A URI reference that identifies the specific occurrence of the problem.

Errors will also include our trace id (see Crezco-Trace-Id (string), below) in an extension field.

Valid Problem Detail Error Types

Example

{
  "Type": "https://api.crezco.com/api/errors/not-found",
  "Title": "Not Found",
  "Status": 404,
  "Detail": "The API endpoint you requested could not be found or you have requested a resource that does not exist",
  "Extensions": {
    "trace": "dd16bbae90ece3b3613fe66fe9b4698d"
  }
}

Error Response Body with Validation Errors

In the case of validation errors returning a 400 Bad Request status code the ProblemDetails structure will also include an Errors array which contain additional error details in the form of key/value pairs mapping a property name to an array of specific validation errors.

Example

{
  "Type": "https://api.crezco.com/api/errors/validation-failed",
  "Title": "Validation Failed",
  "Status": 400,
  "Detail": "The data submitted to the endpoint was incorrect",
  "Errors": {
    "PropertyA": ["Problem1", "Problem2"],
    "PropertyB": ["Problem1"]
  },
  "Extensions": {
    "trace": "68a80748a895ffd5504ac04c9287ea9f"
  }
}

Common Response Headers

All API calls will include the following header in the response

Crezco-Trace-Id (string) - Unique ID for this request. Make a note of this if you are contacting support. This will be our internal trace id to aid troubleshooting.

Common Issues

`400 - Contains <param> when calling create`

This error is most often seen when making a call to Create Organisation endpoint with an OrganisationId or UserId parameter set.

Unfortunately OpenAPI and associated generators (Swagger, ReadMe, etc) will auto-fill this parameter with a value, however including it within the request will cause a validation exception.

🚧
Incorrect - empty GUID

{
  "OrganisationId": "00000000-0000-0000-0000-000000000000",
  // other fields...
}

👍
Correct - field is not included

{
  // OrganisationId is not present
  // other fields...
}

👍
Correct - field is explicitly set to null

{
  "OrganisationId": null,
  // other fields...
}

`400 - ...no active users with the Admin role`

When creating an Organisation there must be at least one active Admin user present.

🚧
Incorrect - Admin user is explicitly set to inactive

{
     "partnerClientId": "Your-Unique-ID",
     "companiesHouseNumber": "11752182",
     "companyName": "Crezco LIMITED",
     "users": [
          {
               "email": "joe.bloggs@crezco.com",
               "firstName": "Joe",
               "lastName": "Bloggs",
               "role": "Admin",
               "active": false
          }
     ]
}

👍
Correct - at least one active Admin

{
     "partnerClientId": "Your-Unique-ID",
     "companiesHouseNumber": "11752182",
     "companyName": "Crezco LIMITED",
     "users": [
          {
               "email": "joe.bloggs@crezco.com",
               "firstName": "Joe",
               "lastName": "Bloggs",
               "role": "Admin"
               "active": true
          }
     ]
}