API Reference

Error Handling

Common Return Codes

The Partner 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 Partner 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
  • 5XX - Something went wrong with our servers. Wait a while and try again (this is rare)

Common Error 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"
  }
}

Validation Error Body

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 Returned 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": "[email protected]",
               "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": "[email protected]",
               "firstName": "Joe",
               "lastName": "Bloggs",
               "role": "Admin"
               "active": true
          }
     ]
}