Skip to content

Error Handling

DeCA API errors follow the standard ProblemDetails format.

{
  "title": "Solicitud no válida",
  "status": 400,
  "detail": "La petición contiene errores de validación.",
  "errors": [
    {
      "field": "ContractualCharger.TaxIdentificationNumber",
      "message": "El valor 'X9999999Z' no es un NIF/NIE/CIF español válido (Art. 6.a)."
    }
  ]
}

Notes on the format:

  • title is a fixed text depending on the error type ("Solicitud no válida" for 400, "Recurso no encontrado" for 404, "Eliminación no permitida" for 409, "Servicio no disponible" for 503).
  • errors is an array of { "field": "...", "message": "..." } objects, one per validation error found.
  • errors is only present for 400 Bad Request errors raised by business validation rules.

Most common HTTP codes:

  • 400 Bad Request: missing required field, invalid tax identifier (Spanish NIF/CIF/NIE for contractualCharger, or Spanish NIF/NIE/CIF / VIES-style foreign identifier for actualCarrier), incomplete articulated vehicle, invalid weight, or invalid notification address.
  • 401 Unauthorized: missing Authorization header or invalid credentials.
  • 404 Not Found: no DeCA exists with the specified id.
  • 409 Conflict: DELETE only; more than 7 days have passed since the DeCA was created, so it can no longer be deleted.
  • 503 Service Unavailable: error uploading PDF to Azure Blob Storage (operation is aborted).

Relevant validation rules:

  • contractualCharger, actualCarrier, shipments, vehicle, and transportDate are required and must not be empty.
  • contractualCharger.taxIdentificationNumber must be a valid Spanish NIF/NIE/CIF.
  • actualCarrier.taxIdentificationNumber accepts a valid Spanish NIF/NIE/CIF or a VIES-style foreign tax identifier (ISO 3166-1 alpha-2 country code other than ES + up to 12 alphanumeric characters with at least one digit), since the actual carrier may be a foreign company carrying out domestic transport.
  • shipments[].weightKg must be positive when provided.
  • shipments[].packageCount is optional, but must be positive when provided.
  • Each shipment must include at least one of weightKg or alternativeMagnitude.
  • vehicle.tractorLicensePlate and vehicle.semitrailerLicensePlate must both be present or both absent.
  • vehicle.licensePlate is required unless both vehicle.tractorLicensePlate and vehicle.semitrailerLicensePlate are provided (complete articulated combination), in which case it is optional and not printed on the PDF if omitted.
  • recipient.address must be a valid email for Email channel or E.164 format for SMS/WhatsApp.
  • logo is optional; format is detected by byte signature during PDF/email generation.

Connection issues:

  • In the event of connection issues with SDH, you may encounter errors such as Unable to resolve the remote name: 'deca.solmicrosdh.com'.
    You can test this by entering the URL https://deca.solmicrosdh.com/api into a browser.
    It should display something like this:

    problemaconexion

  • Logos with a very large base64 representation may cause connection errors or result in a 403-Forbidden response.